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About T his B ook 


This book teaches you all about the Java language and how to useit to create 
appletsand applications. By thetimeyou get through with thisbook, you'll know 
enough about J ava to do just about anything, inside an applet or out. 


Who Should Read This B ook 


This book is intended for people with at least some basic programming back- 
ground, which includes people with years of programming experience or people 
with only asmall amount of experience. If you understand what variables, loops, 
and functions are, you'll bejust fine for this book. T hesorts of peoplewho might 
want to read this book include you, if 


You're areal whiz at HT ML, understand CGI programming (in perl, 
AppleScript, Visual Basic, or some other popular CG! language) pretty 
well, and want to move on to the next level in W eb page design. 


You had some Basic or Pascal in school and you have a basic grasp of 
what programming is, but you've heard J ava is easy to learn, really 
powerful, and very cool. 

You've programmed C and C ++ for many years, you've heard this] ava 
thing is becoming really popular and you’re wondering what all the fuss 
is all about. 

You've heard that J ava is really good for W eb-based applets, and you're 
curious about how good it is for creating more general applications. 


W hat if you know programming, but you don’t know object-oriented program- 
ming? Fear not. T his book assumes no background in object-oriented design. If 
you know object-oriented programming, in fact, the first couple of days will be 
easy for you. 


H ow T his B ook Is Structured 


This book is intended to be read and absorbed over the course of three weeks. 
D uring each week, you'll read seven chapters that present concepts related to the 
Java language and the creation of applets and applications. 


Conventions 


Note: A N ote box presents interesting pieces of information related to the surround- 
ing discussion. 


Technical Note: A T echnical N ote presents specific technical information related to 
the surrounding discussion. 


Tip: A Tip box offers advice or teaches an easier way to do something. 


Caution: A Caution box alerts you to a possible problem and gives you advice to 
avoid it. 


Warning: A Warning box advises you about potential problens and helps you steer 
clear of disaster. 

N ew terms are introduced in N ew T erm boxes, with the term in italics. 

A typeicon identifies some new HTML code that you can typein yourself. 


An Output icon highlights what the same H T ML code looks like when viewed by 
either N etscape or M osaic. 


An analysis icon alerts you to the author’s line-by-line analysis. 


ToEric, for all the usual reasons 
(moral support, tupid questions, comfort in dark times). 
LL 


For RKJP, ARL, and NMH 
the three most important people in my life 
CLP 
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Introduction 


The World Wide W eb, for much of its existence, has been a method for distributing passive 
information to awidely distributed number of people T heW eb has, indeed, been exceptionally 
good for that purpose W ith theaddition of formsand imagemaps, W eb pages began to become 
interactive— but theinteraction was often simply anew way to get at thesameinformation. T he 
limitations of W eb distribution were all too apparent once designers began to try to stretch the 
boundaries of what the W eb can do. Even other innovations, such as N etscape’s server push to 
create dynamic animations, were merely clever trickslayered on top of a framework that wasn’t 
built to support much other than static documents with images and text. 


Enter Java, and the capability for Web pages of containing Java applets. Applets are small 
programs that create animations, multimediapresentations, real-time(video) games, multi-user 
networked games, and real interactivity— in fact, most anything asmall program can do, J ava 
appletscan. D ownloaded over thenet and executed insideaW eb pageby abrowser that supports 
Java, applets are an enormous step beyond standard W eb design. 


T hedisadvantage of J avais that to create] ava applets right now, you need to write then in the 
Java language. Java is a programming language, and as such, creating Java applets is more 
difficult than creatingaW eb pageor aform usingH T M L. Soon therewill betoolsand programs 
that will make creating J ava applets easier— they may be available by thetime you read this. For 
now, however, theonly way to delveinto J avaisto learn thelanguageand start playing with the 
raw J avacode Even when thetoolscomeout, you may want to do morewith J avathan thetools 
can provide, and you’re back to learning the language. 


T hat’s whereT each Y oursaf J avain 21 D ayscomesin. T his book teaches you all about the] ava 
language and how to use it to create not only applets, but also applications, which are more 
general J ava programs that don’t need to run insideaW eb browser. By thetime you get through 
with this book, you'll know enough about J ava to do just about anything, inside an applet or 
out. 


Who Should Read This B ook 


Teach Yourself Java in 21 Daysis intended for people with at least some basic programming 
background— which includes people with years of programming experience and people with 
only asmall amount of experience. If you understand what variables, loops, and functions are, 
you'll be just fine for this book. T he sorts of people who might want to read this book include 
you, if one or more of the following is true 


Ll] You’rea real whiz at HTML, understand CGI programming (in perl, AppleScript, 
Visual Basic, or some other popular CG! language) pretty well, and want to move 
onto the next level in W eb page design. 
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(| You had some Basic or Pascal in school, you've got a basic grasp of what programming 
is, but you’ve heard J ava is easy to learn, really powerful, and very cool. 

(| You've programmed C and C ++for many years, you've heard this] ava thing is 
becoming really popular, and you’re wondering what all the fuss is all about. 


“] You've heard that J ava is really good for W eb-based applets, and you’re curious about 
how good it is for creating more general applications. 


W hat if you Know programming, but you don’t know object-oriented programming? F ear not. 
Teach Y ourself Java in 21 Daysassumes no background in object-oriented design. If you know 
object-oriented programming, the first couple of days will be easy for you. 


W hatif you’rearank beginner?T hisbook might movealittlefast for you. J avaisagood language 
to start with, though, and if you take it slow and work through all the examples, you may still 
be able to pick up Java and start creating your own applets. 


H ow This B ook Is Organized 


Teach Y ourself J ava in 21 D aysdescribes} ava primarily in its current state— what’s known asthe 
beta API (Application Programming Interface). T his is the version of J ava that N etscape and 
other browsers, such as Spyglass’s M osaic, support. A previous version of J ava, the alpha API, 
was significantly different from the version described in this book, and thetwo versionsarenot 
compatible with each other. T here are other books that describe only the alpha API, and there 
may still be programs and browsers out there that can only run using alpha] ava programs. 


Teach Y ourself J ava in 21 D aysuses primarily J ava beta because that is the version that is most 
current and isthe version that will continue to be used in thefuture. T healphaAPI is obsolete 
and will eventually die out. If you learn J ava using betaAPI, you'll be much better prepared for 
any future changes (which will be minor) than if you have to worry about both APIs at once 


Javaisstill in devdopment. “Beta” meansthat J avaisnot complete and that things may change 
between thetimethis book is being written and thetimeyou read this. K eep thisin mind as you 
work with J ava and with thesoftware you'll useto create and compile programs. If things aren’t 
behaving the way you expect, check the W eb sites mentioned at theend of thisintroduction for 
more information. 


Teach Y oursdf} avain 21 D ayscoversthe] avalanguageand itsclasslibrariesin 21 days, organized 
as three separate weeks, Each week covers a different broad area of developing J ava applets and 
applications. 


In the first week, you'll learn about the J ava language itself: 


[ Day 1 isthe basic introduction: what J avais, why it’s cool, and how to get the 
software. You'll also create your first J ava applications and applets. 


On Day 2, you'll explore basic object-oriented programming concepts as they apply to 
Java. 


On Day 3, you start getting down to details with the basic J ava building blocks: data 
types, variables, and expressions such as arithmetic and comparisons. 


D ay 4 goes into detail about how to deal with objects in J ava: how to create them, 
how to access their variables and call their methods, and how to compare and copy 
them. You'll also get your first glance at the J ava class libraries. 


On Day 5, you'll learn more about J ava with arrays, conditional statements. and 
loops. 


Day 6 isthe best one yet. You'll learn how to create classes, the basic building blocks 
of any Java program, as well as how to put together aJ ava application (an application 
being aJava program that can run on its own without a W eb browser). 


Day 7 builds on what you learned on Day 6. On Day 7, you'll learn more about how 
to create and use methods, including overriding and overloading methods and 
creating constructors. 


W eek 2 is dedicated to applets and the J ava class libraries: 


[) Day 8 provides the basics of applets— how they're different from applications, how to 
create them, and the most important parts of an applet’s life cycle You'll also learn 
how to create H T ML pages that contain J ava applets. 

On Day 9, you'll learn about the J ava classes for drawing shapes and characters to the 
screen— in black, white, or any other color. 

On Day 10, you'll start animating those shapes you learned about on D ay 9, includ- 
ing learning what threads and their uses are. 

Day 11 covers more detail about animation, adding bitmap images and audio to the 
soup. 

Day 12 delves into interactivity— handling mouse and keyboard clicks from the user 
in your J ava applets. 

Day 13 is ambitious; on that day you'll learn about using J ava’s Abstract W indowing 
T oolkit to create a user interface in your applet including menus, buttons, checkboxes, 
and other edements. 

On Day 14, you explore the last of the main J ava class libraries for creating applets: 
windows and dialogs, networking, and a few other tidbits. 


W eek 3 finishesup with advanced topics, for when you start doing larger and morecomplex] ava 
programs, or when you want to learn more: 


| On Day 15, you'll learn more about the J ava language’s modifiers— for abstract and 
final methods and classes as well as for protecting a class's private information from 
the prying eyes of other classes. 
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"| Day 16 covers interfaces and packages, useful for abstracting protocols of methods to 
aid reuse and for the grouping and categorization of classes. 


_] Day 17 covers exceptions: errors and warnings and other abnormal conditions, 
generated either by the system or by you in your programs. 


“| Day 18 builds on the thread basics you learned on D ay 10 to give a broad overview of 
multithreading and how to useit to allow different parts of your J ava programs to run 
in paralld. 

On Day 19, you'll learn all about the input and output streams in J ava’s 1/O library. 
D ay 20 teaches you about native code— how to link C codeinto your J ava programs 
to provide missing functionality or to gain performance. 

Finally, on Day 21, you'll get an overview of some of the “behind-the-scenes” techni- 
cal details of how Java works: the bytecode compiler and interpreter, the techniques 
Java uses to ensure the integrity and security of your programs, and the] ava garbage 
collector. 


Conventions Used in T his Book 


T ext that you type and text that should appear on your screen is presented in monospace type: 
It will look like this. 


to mimic the way text lookson your screen. V ariables and placeholderswill appear in monospace 
italic. 


The end of each chapter offers common questions asked about that day’s subject matter with 
answers from the authors. 


Web Sites for Further Information 


Before, while, and after you read this book, there are two W eb sites that may be of interest to 
you as a] ava developer. 


The official Java web site is at http://java.sun.com/. At this site, you'll find the Java 
development software, the H ot] ava web browser, and online documentation for all aspects of 
the} ava language. It has several mirror sites that it lists online, and you should probably usethe 
site “closest” to you on the! nternet for your downloading and J avaW eb browsing. T hereisalso 
asite for developer resources, called Gamelan, at http: //www.gamelan.com/. 


This book also has a companion W eb site at http://www. Ine. com/Web/Java/. Information at 
that siteincludes examples, moreinformation and background for this book, correctionsto this 
book, and other tidbits that were not included here. 
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H ello and welcometoT each Y oursaf] avain 21 D ays! Starting today and for thenext three weeks 
you'll learn all about the] avalanguageand how to useit to createapplets, aswell ashow to create 
stand-alone J ava applications that you can use for just about anything. 


NEWe Anapple isadynamic and interactive program that can run inside a W eb page displayed 
TERM by aJava-capable browser such as H ot) ava or N etscape 2.0. 


TheH ot] ava browse isa W orld Wide W eb browser used to view W eb pages, follow links, and 
submit forms. It can also download and play applets on the reader’s system. 


T hat’s the overall goal for the next three weeks. T oday, the goals are somewhat more modest, 
and you'll learn about the following: 


“| What exactly Java and H ot] ava are, and their current status 

(|) Why you should learn J ava— its various features and advantages over other program- 
ming languages 

Getting started programming in J ava— what you'll need in terms of software and 
background, as well as some basic terminology 


H ow to create your first J ava programs— to close this day, you'll create both a simple 
Java application and a simple J ava applet! 


What Is J ava? 


Javaisan object-oriented programming language developed by Sun Microsystems, acompany 
best known for its high-end Unix workstations. M odeled after C-H, the Java language was 
designed to besmall, simple, and portable across platforms and operating systems, both at the 
source and at the binary level (more about this later). 


Java is often mentioned in the same breath as H ot] ava, a W orld W ide W eb browser from Sun 
like N etscape or M osaic (see Figure 1.1). What makes H ot] ava different from most other 
browsers is that, in addition to all its basic W eb features, it can also download and play applets 
on the reader's system. Applets appear in a W eb page much in the same way as images do, but 
unlike images, applets are dynamic and interactive. Applets can be used to create animations, 
figures, or areas that can respond to input from thereader, games, or other interactive effects on 
the same W eb pages among the text and graphics. 


Although H ot] ava was the first W orld W ide W eb browser to be able to play J ava applets, J ava 
support is rapidly becoming availablein other browsers. N etscape 2.0 provides support for J ava 
applets, and other browser developers have also announced support for Java in forthcoming 
products. 


Figure 1.1. 
TheH ot} ava browse. File Options Navigate Gote 
URL: ety://java.sum.com/ 


@ sun oi 


Hot] AvA 


Welcome (Mirror Sites) 
Welcome to Sun's Java(tayHatevettn) heme page. Sun's Java 
Sun 


Hetlavaitm) Browser is 2 dynamic, extenshle WWW browrer that showcases the copabiitins of the 
Jorn Pragrecnring Longuoge 
© Search oor Web pages 

You can search our an-lne Web pages, or cur maine Ist archives, 


Announcements 


$ 
¥ ‘The 1.0 Pre-Beta release of the Java Developers Kit is mow available See the Jorn 
Developers it page tar full Getadls ond Gowndaading instructions. 


‘The Alpha 3 release for Microsoft Windows NT amd Windows 9S be now available. See the 
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Tocreatean applet, you writeit in the] avalanguage, compileit using a] avacompiler, and refer 
to that applet in your HT M L W eb pages. You put theresulting H T M L and J avafileson aW eb 
sitemuch in thesameway that you makeordinary H T M L and imagefilesavailable. T hen, when 
someone using the H ot] ava browser (or other J ava-aware browser) views your page with the 
embedded applet, that browser downloads the applet to the local system and executes it, and 
then the reader can view and interact with your applet in all its glory (readers using other 
browsers won't see anything). You'll learn more about how applets, browsers, and the W orld 
W ide W eb work together further on in this book. 


T heimportant thing to understand about J avaisthat you can do so much morewith it besides 
create applets. Java was written as a full-fledged programming language in which you can 
accomplish the same sorts of tasks and solve the same sorts of problems that you can in other 
programming languages, such asC or C ++ H otJavaitself, including all thenetworking, display, 
and user interface elements, is written in Java. 
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J ava’s Past, Present, and Future 


T he] ava language was developed at Sun M icrosystemsin 1991 as part of aresearch project to 
develop software for consumer electronics devices— television sets, VCRs, toasters, and the 
other sorts of machines you can buy at any department store. J ava’s goals at that time were to 
besmall, fast, efficient, and easily portable to a wide range of hardware devices. It isthosesame 
goalsthat made] avaan ideal languagefor distributing executableprograms viatheW orld Wide 
W eb, and also ageneral-purpose programming languagefor developing programs that are easily 
usable and portable across different platforms. 


T he] avalanguagewasused in several projectswithin Sun, but did not get very much commercial 
attention until it was paired with H ot) ava. H ot) ava was written in 1994 in amatter of months, 
both as a vehicle for downloading and running applets and also as an example of the sort of 
complex application that can be written in J ava. 


At thetime this book is being written, Sun has released the beta version of the] ava D eveloper’s 
Kit (JDK), which includes tools for developing J ava applets and applications on Sun systems 
running Solaris 2.3 or higher for W indowsNT and for W indows95. By thetime you read this, 
support for J ava development may have appeared on other platforms, either from Sun or from 
third-party companies. 


N otethat becausethe] D K iscurrently in beta, it isstill subject to changebetween now and when 
it isofficially released. Applets and applicationsyou write using the] D K and using theexamples 
in this book may require some changes to work with future versions of the}D K. However, 
becausethe] avalanguagehasbeen around for several yearsand has been used for several projects, 
the language itself is quite stable and robust and most likely will not change excessively. K eep 
this beta status in mind as you read through this book and as you develop your own Java 
programs. 


Support for playing J ava programs is a little more confusing at the moment. Sun’s H ot ava is 
not currently included with theBeta] D K; theonly availableversion of H ot] avaisan older alpha 
version, and, tragically, applets written for the alpha version of J ava do not work with the beta 
JDK, and viceversa. By thetimeyou read this, Sun may havereleased anewer version of H ot] ava 
which will enable you to view applets. 


T hej DK doesincludean application called appletviewer that allowsyou to test your J avaapplets 
as you writethem. If an applet worksin theappletviewer, it should work with any J ava-capable 
browser. You'll learn more about applet viewer later today. 


W hat’sin store for the future? In addition to the final J avarelease from Sun, other companies 
have announced support for J avain their own W orld W ide W eb browsers. N etscape Commu- 
nicationsC orporation hasalready incorporated J avacapabilitiesinto the2.0 version of their very 
popular N etscape N avigator W eb browser— pages with embedded J ava applets can be viewed 
and played with N etscape. W ith support for J ava available in as popular a browser as N etscape, 


toolsto help develop J avaapplications(debuggers, development environments, and so on) most 
likely will be rapidly available as well. 


Why Learn J ava? 


At themoment, probably the most compelling reason to learn J ava— and probably the reason 
you bought thisbook— isthat H ot] avaappletsarewritten in J ava. Even if that werenot the case, 
Java as a language has significant advantages over other languages and other programming 
environmentsthat makeit suitable for just about any programming task. T his section describes 
some of those advantages. 


J ava Is Platform-I ndependent 


Platform independence is one of the most significant advantages that Java has over other 
programming|languages, particularly for systemsthat need to work on many different platforms. 
Java is platform-independent at both the source and the binary level. 


NEWe- Platform-indeoendence is a program's capability of moving easily from one computer 
TERM _ system to another. 


At the source level, J ava’s primitive data types have consistent sizes across all development 
platforms. J ava’s foundation class libraries make it easy to write code that can be moved from 
platform to platform without the need to rewrite it to work with that platform. 


Platform-independence doesn’t stop at the source level, however. Java binary files are also 
platform-independent and can run on multiple problems without the need to recompile the 
source. H ow does this work? J ava binary files are actually in a form called bytecodes. 


NEWe- Bytecodesareaset of instructions that looksa lot likesome machine codes, but that isnot 
TERM _ specific to any one processor. 


Normally, when you compilea program written in C or in most other languages, the compiler 
translates your program into machine codes or processor instructions. T hose instructions are 
specific to the processor your computer is running— so, for example, if you compile your code 
onaPentium system, theresulting program will run only on other Pentium systems. If you want 
to use the same program on another system, you have to go back to your original source, get a 
compiler for that systen, and recompile your code. Figure 1.2 shows the result of this systen: 
multiple executable programs for multiple systems. 


Things are different when you write codein J ava. T he] ava development environment has two 
parts: a Java compiler and aJ ava interpreter. The] ava compiler takes your J ava program and 
instead of generating machine codes from your source files, it generates bytecodes. 
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Figure 1.2. Binary File 
a i (Pentium) 
Traditional compiled 
programs. 
Your ode Compiler (Pentium) Binary File 
(PowerPC) 
Compiler (PowerPC) Binary File 
(SPARC) 


Compiler (SPARC) 


Torunajavaprogram, you run aprogram called abytecode interpreter, which in turn executes 
your] avaprogram (seeF igure 1.3). You can either run theinterpreter by itself, or— for applets— 
thereisa bytecode interpreter built into H ot} ava and other J ava capable browsers that runsthe 


applet for you. 


Window 


Figure 1,3. 
Java programs. yNX 
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W hy go through all the trouble of adding this extra layer of the bytecode interpreter? H aving 
your] avaprogramsin bytecodeform meansthat instead of being specific to any onesystem, your 
programs can berun on any platform and any operating or window system as long as the] ava 
interpreter is available. T his capability of a single binary file to be executable across platforms 
is crucial to what enables applets to work, because the W orld W ideW eb itself is also platform- 
independent. J ust asH T M L filescan beread on any platform, so appletscan beexecuted on any 
platform that is a] ava-capable browser. 


The disadvantage of using bytecodes isin execution speed. Because system-specific programs 
run directly on the hardware for which they arecompiled, they run significantly faster than J ava 
bytecodes, which must be processed by theinterpreter. For many J avaprograms, thespeed may 
not bean issue. I f you writeprogramsthat requiremoreexecution speed than the] avainterpreter 
can provide, you haveseveral solutions availableto you, including being ableto link nativecode 
into your J avaprogram or usingtoolsto convert your J ava bytecodesinto native code. N otethat 
by using any of thesesolutions, you losethe portability that] ava bytecodes provide. You'll learn 
about each of these mechanisms on D ay 20. 


Java Is Object-Oriented 


To some, object-oriented programming (OOP) technique is merely a way of organizing 
programs, and it can be accomplished using any language. W orking with areal object-oriented 
languageand programming environment, however, enables you to takefull advantageof object- 
oriented methodology and its capabilities of creating flexible, modular programs and reusing 
code. 


M any of J ava’s object-oriented concepts are inherited from C-H, the language on which it is 
based, but it borrows many concepts from other object-oriented languages as well. Like most 
object-oriented programming languages, | ava includes a set of class libraries that provide basic 
datatypes, system input and output capabilities, and other utility functions. T hese basic classes 
are part of the J ava deveopment kit, which also has classes to support networking, common 
Internet protocols, and user interface toolkit functions. Because these class libraries are written 
in J ava, they are portable across platforms as all J ava applications are. 


You'll learn more about object-oriented programming and J ava tomorrow. 


Java Is Easy to Learn 


In addition to its portability and object-orientation, one of Java's initial design goals was to be 
small and simple, and therefore easier to write, easier to compile, easier to debug, and, best of 
all, easy to learn. K eeping the language small also makes it more robust because there are fewer 
chances for programmersto make difficult-to-find mistakes. D espite its sizeand simpledesign, 
however, J ava still has a great deal of power and flexibility. 
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Java is modeled after C and C-H, and much of the syntax and object-oriented structure is 
borrowed from thelatter. If you arefamiliar with C +, learning] ava will be particularly easy for 
you, because you have most of the foundation already. 


Although J ava looks similar to C and C +4, most of the more complex parts of those languages 
have been excluded from Java, making the language simpler without sacrificing much of its 
power. T hereareno pointersin Java, nor isthere pointer arithmetic. Strings and arrays are real 
objects in Java. Memory management is automatic. To an experienced programmer, these 
omissions may be difficult to get used to, but to beginners or programmers who have worked 
in other languages, they make the J ava language far easier to learn. 


Getting Started with 
Programming in Java 


Enough background! Let’s finish off this day by creating two real J ava programs: a stand-alone 
Java application and an applet that you can view in either in the appletviewer (part of the] D K) 
or in aJava-capable browser. Although both these programsare extremely simple, they will give 
you an idea of what aJ ava program looks like and how to compile and run it. 


Getting the Software 


In order to write] ava programs, you will, of course, need aJ ava development environment. At 
thetime this book is being written, Sun’s] ava D eveopment Kit provides everything you need 
to start writing] avaprograms. The] DK isavailablefor Sun SPARC systemsrunningSolaris2.2 
or higher and for Windows NT and Windows 95. You can get the] DK from several places: 


“| TheCD-ROM that came with this book contains the full JD K distribution. See the 
CD information for installation instructions. 

“| TheJDK can be downloaded from Sun’sJavaFTP site at ftp: //java.sun.com/pub/ Or 
from amirror site (ftp: //www.blackdown.org/pub/Java/pub/is one). 


Note: T he] ava D evdopment Kit is currently in beta release. By the time you read 
this, The}DK may be available for other platforms, or other organizations may be 
selling J ava development tools as well. 


Although N etscape and other J ava-aware browsers provide an environment for playing J ava 
applets, they do not provide a mechanism for developing J ava applications. For that, you need 
separate tools— merely having a browser is not enough. 


Applets and Applications 


Java applications fall into two main groups: applets and applications. 


Applets, asyou have learned, are] ava programsthat are downloaded over the W orld W ideW eb 
and executed by a W eb browser on the reader’s machine. Applets depend on a J ava-capable 
browser in order to run (although they can also be viewed using a tool called the appletviewer, 
which you'll learn about later today). 


Javaapplicationsaremoregeneral programswritten in the] avalanguage. J avaapplicationsdon’t 
requirea browser to run, and in fact, Java can be used to createmost other kinds of applications 
that you would normally use a more conventional programming language to create. H ot] ava 
itself is a} ava application. 


A single] ava program can bean applet or an application or both, devending on how you write 
that program and the capabilities that program uses. Throughout this first week, you'll be 
writing mostly H ot} ava applications; then you’ll apply what you've learned to write applets in 
W eek 2. If you're eager to get started with applets, be patient. Everything that you learn while 
you'recreating simpleJ avaapplicationswill apply to creating applets, and it’s easier to start with 
the basics before moving onto the hard stuff. You'll be creating plenty of applets in W eek 2. 


Creating a J ava Application 


Let'sstart by creating asimple] avaapplication: theclassicH ello W orld examplethat all language 
books use to begin. 


Aswith all programming languages, your J ava source files are created in a plain text editor, or 
in an editor that can save files in plain ASCII without any formatting characters. On U nix, 
emacs, ped, or vi will work; on Windows, N otepad or DOS Edit are both text editors. 


Fire up your editor of choice, and enter the Java program shown in Listing 1.1. T ype this 
program, as shown, in your text editor. Be careful that all the parentheses, braces, and quotes 
are there 


Type Listing 1.1. Your first Java application. 


1: class HelloWorld { 

2 public static void main (String args[]) { 
3: System.out.println("Hello World!"); 
4: } 

5: } 
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program; they're there so | can refer to specific line numbers when | explain what’s 


y Warning: T he numbers before each line are part of the listing and not part of the 
~ going on in the program. Do not includethem in your own file. 


This program has two main parts: 


Analyss 


All the program is enclosed in a class definition— here, a class called He11oworid. 


The body of the program (here, just the one line) is contained in a routine called 
main(). In Java applications, asin aC or C-++program, main) is the first 
routine that is run when the program is executed. 


You'll learn more about both these parts of a] ava application as the book progresses. 


Once you finish typing the program, save thefile. Conventionally, J ava source files are named 
thesamenameastheclass they define, with an extension of . java. T hisfileshould thereforebe 
called HelloWorld. java 


N ow, let’s compile the source file using the J ava compiler. In Sun’s]D K, the] ava compiler is 
called javac. 


Tocompileyour | avaprogram, M akesurethejavac program isin your execution path and type 
javac followed by the name of your source file: 


javac HelloWorld.java 


Note: In these examples, and in all the examples throughout this book, we'll be 
using Sun’s] ava compiler, part of the] DK. If you have a third-party development 
environment, check with the documentation for that program to see how to 
compile your J ava programs. 


The compiler should compile the file without any errors. If you get errors, go back and make 
sure that you've typed the program exactly as it appears in Listing 1.1. 


W hen the program compiles without errors, you end up with afile called H elloW orld.class, in 
the same directory as your source file. T his is your Java bytecode file. You can then run that 
bytecode file using the] ava interpreter. In the}DK, the] ava interpreter is called simply java. 
M akesurethejavaprogram isin your path and type java followed by thenameof thefilewithout 
the .class extension: 


java HelloWorld 


If your program was typed and compiled correctly, you should get the string "Hello World!" 
printed to your screen as a response. 


Note: Remember, the] ava compiler and the] ava interpreter are different things. 
You use the] ava compiler (javac) for your Java source files to create .class files, and 
you use the] ava interpreter (java)to actually run your class files. 


Creating a J ava Applet 


Creating appletsisdifferent from creating asimpleapplication, because] avaappletsrun and are 
displayed insideaW eb pagewith other pageelements and assuch havespecial rulesfor how they 
behave. Because of these special rules for applets in many cases (particularly the simple ones), 
creating an applet may be more complex than creating an application. 


For example, to do asimpleH ello W orld applet, instead of merely being ableto print amessage, 
you have to create an applet to make space for your message and then use graphics operations 
to paint the message to the screen. 


Note: Actually, if you run theH ello World application as an applet, the He110 
World message prints to a special window or to alog file, depending on how the 
browser has screen messages set up. It will not appear on the screen unless you 
write your applet to put it there. 


In thenext example, you createthat simpleH ello W orld applet, placeit insideaW eb page, and 
view the result. 


First, you set up an environment so that your J ava-capable browser can find your HTM L files 
and your applets. M uch of thetime, you'll keeo your HT ML files and your applet codein the 
same directory. Although thisisn’t required, it makes it easier to keep track of each element. In 
this example, you use a directory called HTM L that contains all the files you'll need. 


mkdir HTML 


N ow, open up that text editor and enter Listing 1.2. 
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Type Listing 1.2. The Hello World applet. 


import java.awt.Graphics; 


: class HelloWorldApplet extends java.applet.Applet { 


g.drawString("Hello world!", 5, 25); 


1: 
2 
3 
4: 
5: public void paint(Graphics g) { 
6: 
7 } 

8: 


} 


Save that file inside your HTmt directory. J ust like with J ava applications, give your file a name 
that has thesamenameas the class. In thiscase, thefilename would beHelloworldApplet. java. 


Features to note about applets? T here are a couple!'d like to point out: 


(] The import line at the top of the file is somewhat analogous to an #include statement 
in C; it enables this applet to interact with the]DK classes for creating applets and for 
drawing graphics on the screen. 


(| The paint() method displays the content of the applet onto the screen. H ere, the 
string Hello World gets drawn. Applets use several standard methods to take the place 
of main), which include init ) to initialize the applet, start () to start it running, 
and paint() to display it to the screen. You'll learn about all of these in W eek 2. 


N ow, compile the applet just as you did the application, using javac, the] ava compiler. 
javac HelloWorldApplet.java 


Again, just asfor applications, you should now haveafilecalled H elloW orldApplet.classin your 
HTML directory. 


To includean applet in aW eb page, you refer to that applet in the HT M L code for that W eb 
page. H ere, you create a very simple HT ML filein the HTML directory (see Listing 1.3). 


Type Listing 1.3. The HTML with the applet in it. 


: <HTML> 

: <HEAD> 

: <TITLE>Hello to Everyone!</TITLE> 

: </HEAD><BODY> 

: <P>My Java applet says: 

: <APPLET CODE="HelloWorldApplet.class" WIDTH=15@ HEIGHT=25> 
: </BODY> 

: </HTML> 


ONO RWN— 


Analysis You refer to an appletin your HTM L files with the <appLet> tag. You'll learn more about 


<APPLET> later on, but here are two things to note: 


Use the cove attribute to indicate the name of the class that contains your applet. 

U se the wipTH and HEIGHT attributes to indicate the size of the applet. T he browser uses 
these values to know how big a chunk of space to leave for the applet on the page. 

H ere, abox 150 pixels wide and 25 pixels high is created. 


SavetheH TM L filein yourH T ML directory, with adescriptivename (for example, you might 
name your HTML file the same name as your applet— H ellowW orldApplet.html). 


And now, you'reready for the final test— actually viewing theresult of your applet. T o view the 
applet, you need one of the following: 


A browser that supports J ava applets, such as N etscape 2.0. 

The appletviewer application, which is part of the} DK. T he appletviewer is not a 

W eb browser and won't enable you to see the entire W eb page, but it’s acceptable for 
testing to see how an applet will look and behave if there is nothing else available 


Note: D o not use the alpha version of H ot] ava to view your applets; applets 
developed with the betaJD K and onward cannot be viewed by the alpha H ot] ava. 
If, by the time you read this, there is a more recent version of H ot] ava, you can use 
that one instead. 


If you’reusing aJ ava-capable browser such asN etscapeto view your applet files, you can usethe 
Open Local... item under the File menu to navigate to the HT ML file containing the applet 
(make sure you open the HT ML file and not the classfile). You don’t need to install anything 
on aW eb server yet; all this works on your local system. 


If you don't havea W eb browser with J ava capabilities built into it, you can usetheappletviewer 
program to view your J avaapplet. T o run appletviewer, just indicatethepath to theHT ML file 
on the command line: 


appletviewer HTML/HelloWorldApplet.html 


Tip: Although you can start appletviewer from the same directory as your HTML 
and class files, you may not be able to road that applet without quitting 
appletviewer first. If you start appletviewer from some other directory (asin the 
previous command line), you can modify and recompile your J ava applets and then 
just use the Reload menu item to view the newer version. 
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N ow, if you use the browser to view the applet, you seesomething similar to the image shown 
in Figure 1.4. If you’re using appletviewer, you won't see the text around the applet (my vava 
applet says...), but you will see the Hello worid itself. 


Figure 1.4, 
TheH alo World applet. 
Why Java Applet says: Hello world! 


Summary 


T oday, you got a basic introduction to the J ava language and its goals and features. Javaisa 
programminglanguage, similar to C or C +, in which you can develop awiderangeof programs. 
The most common use of J ava at the moment is in creating applets for H ot) ava, an advanced 
W orld W ideW eb browser also written in J ava. Applets are] ava programs that are downloaded 
and run as part of aW eb page. Applets can create animations, games, interactive programs, and 
other multimedia effects on W eb pages. 


Java's strengths lie in its portability— both at the source and at the binary leva, in its object- 
oriented design— and in its simplicity. Each of these features help make applets possible, but 
they also make] ava an excellent language for writing more general-purpose programs that do 
not requireH ot] avaor other] ava-capable browser to run. T hesegeneral-purpose] ava programs 
are called applications. H ot] ava itself is a] ava application. 


Toend thisday, you experimented with an example applet and an example application, getting 
afeel for the differences between thetwo and how to create, compile, and run J ava programs— 
or, in the case of applets, how to include them in W eb pages. From here, you now have the 
foundation to create more complex applications and applets. 


Q&A 


Q_ I'd like to use H otjava as my regular W eb browser. You haven’t mentioned much 
about H ot ava today. 

A The focus of this book is primarily on programming in J ava and in theH otJava 
Classes, rather than on using H ot] ava itself. Documentation for using the H ot] ava 
browser comes with the H ot] ava package. 

Q | know alot about HTML, but not much about computer programming. Can | 
still write Java programs? 
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A lf you haveno programming experience whatsoever, you most likely will find pro- 
gramming J ava significantly more difficult. H owever, J ava is an excellent language to 
learn programming with, and if you patiently work through the examples and the 
exercises in this book, you should be able to learn enough to get started with J ava. 


According to today’s lesson, Java applets are downloaded via H otJava and run on 
the reader’s system. Isn’t that an enormous security hole? W hat stops someone 
from writing an applet that compromises the security of my system— or worse, 
that damages my system? 


Sun’s J ava team has thought a great deal about the security of applets within J ava- 
capable browsers and has implemented several checks to make sure applets cannot do 
nasty things: 

[| Java applets cannot read or write to the disk on the local system. 

Java applets cannot execute any programs on the local system. 


Java applets cannot connect to any machines on the W eb except for the server 
from which they are originally downloaded. 


In addition, the] ava compiler and interpreter check both the J ava source code and the 
J ava bytecodes to make sure that the] ava programmer has not tried any sneaky tricks 
(for example, overrunning buffers or stack frames). 


T hese checks obviously cannot stop every potential security hole, but they can 
significantly reduce the potential for hostile applets. You'll learn more about security 
issues later on in this book. 


| followed all the directions you gave for creating a J ava applet. | loaded it into 
H ot) ava, but He110 worid didn’t show up. What did | do wrong? 


I'll bet you're using the alpha version of H ot} ava to view the applet. Unfortunately, 
between alpha and beta, significant changes were made as to how applets are written. 
The result is that you can’t view beta applets (as this one was) in the alpha version of 
H ot] ava, nor can you view alpha applets in browsers that expect beta applets. To view 
the applet, eather use a different browser, or use the appletviewer application that 
comes with theJDK. 
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O bject-oriented programming (0 O P) is one of the bigger programming buzzwords of recent 
years, and you can spend years learning all about object-oriented programming methodologies 
and how they can make your life easier than T heO Id W ay of programming. It all comes down 
to organizing your programs in ways that echo how things are put together in the real world. 


T oday, you'll get an overview of object-oriented programming concepts in J ava and how they 
relate to how you structure your own programs: 
(| What classes and objects are, and how they relate to each other 
Thetwo main parts of a class or object: its behaviors and its attributes 
Class inheritance and how inheritance affects the way you design your programs 
Some information about packages and interfaces 


If you’realready familiar with object-oriented programming, much of today’slesson will beold 
hat to you. You may want to skim it and go to amovietoday instead. Tomorrow, you'll get into 
more specific details. 


Thinking in Objects: An Analogy 


Considey, if you will, Legos. Legos, for those who do not spend much time with children, are 
small plastic building blocks in various colors and sizes. T hey havesmall round bits on oneside 
that fit into small round holes on other Legos so that they fit together snugly to create larger 
shapes. W ith different Lego bits(L ego wheels, L ego engines, L ego hinges, Lego pulleys), you can 
put together castles, automobiles, giant robotsthat swallow cities, or just about anything eseyou 
can create. Each Lego bit isasmall object that fits together with other small objectsin predefined 
ways to create other larger objects. 


H ere’s another example. You can walk into acomputer store and, with alittle background and 
often some help, assemble an entire PC computer system from various components: a 
motherboard, aC PU chip, a video card, ahard disk, akeyboard, and so on. Ideally, when you 
finish assembling all the various self-contained units, you have a system in which all the units 
work together to create a larger system with which you can solve the problems you bought the 
computer for in the first place. 


Internally, each of those components may be vastly complicated and engineered by different 
companies with different methods of design. But you don’t need to know how the component 
works, what every chip on the board does, or how, when you press theA key, an “A” gets sent 
to your computer. As the assembler of the overall system, each component you use is a self- 
contained unit, and all you areinterested in is how the units interact with each other. W ill this 
video card fit into theslots on themotherboard and will thismonitor work with this video card? 
W ill each particular component speak the right commands to theother componentsit interacts 
with so that each part of the computer isunderstood by every other part? O nce you know what 


the interactions are between the components and can match theinteractions, putting together 
the overall system is easy. 


W hat does this have to do with programming? Everything. Object-oriented programming 
works in exactly this same way. U sing object-oriented programming, your overall program is 
made up of lots of different self-contained components (objects), each of which has a specific 
rolein the program and all of which can talk to each other in predefined ways. 


Objects and Classes 


O bject-oriented programmingismodeed on how, in thereal world, objects are often madeup 
of many kindsof smaller objects. T hiscapability of combining objects, however, isonly onevery 
general aspect of object-oriented programming. O bject-oriented programming providesseveral 
other concepts and featuresto make creating and using objects easier and more flexible, and the 
most important of these features is that of classes. 


NEWe A cassis a template for multiple objects with similar features. Classes embody all the 
TERM features of a particular set of objects. 


W hen you writea program in an object-oriented language, you don’t define actual objects. You 
define classes of objects. 


For example, you might have a Tree class that describes the features of all trees (has leaves and 
roots, grows, creates chlorophyll). T he Tree class serves as an abstract mode! for the concept of 
a tree— to reach out and grab, or interact with, or cut down a tree you have to have aconcrete 
instance of that tree. Of course, once you have a tree class, you can create lots of different 
instances of that tree, and each different tree instance can have different features (short, tall, 
bushy, drops leaves in Autumn), while still behaving like and being immediately recognizable 
as a tree (see Figure 2.1). 


NEWee An instance of a class is another word for an actual object. If classes are an abstract 
TERM representation of an object, an instance is its concrete representation. 


So what, precisely, isthe difference between an instance and an object? N othing, really. O bject 
isthemoregeneral term, but both instancesand objectsaretheconcreterepresentation of aclass. 
In fact, the terms instance and object are often used interchangeably in OO P language. An 
instance of a tree and a tree object are both the same thing. 


In an examplecloser to thesort of thingsyou might want to do in] avaprogramming, you might 
create a class for the user interface element called abutton. T heButton class defines the features 
of a button (its label, its size, its appearance) and how it behaves (doesit need a single click or 
a double click to activate it, does it change color when it’s clicked, what does it do when it’s 
activated?). Once you define the Button class, you can then easily create instances of that 
button— that is, button objects— that all take on the basic features of the button as defined by 
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the class, but may have different appearances and behavior based on what you want that 
particular button to do. By creating aButton class, you don’t have to keep rewriting the code 
for each individual button you want to usein your program, and you can reuse theButton class 
to create different kinds of buttons as you need them in this program and in other programs. 


Figure 2.1. 


Thetree class and 
tree instances 


Tree 


Tree Class 
(Abstract) 


Tip: If you’re used to programming in C, you can think of a class as sort of 
creating anew composite data type by using struct and typedef. Classes, how- 
ever, can provide much more than just a collection of data, as you’ll discover in the 
rest of today’s lesson. 


When you write a Java program, you design and construct a set of classes. Then, when your 
program runs, instances of thoseclasses are created and discarded as needed. Your task, asa] ava 


programmer, is to create the right set of classes to accomplish what your program needs to 
accomplish. 


Fortunately, you don’t haveto start from the very beginning: the] avaenvironment comes with 
a library of classes that implement a lot of the basic behavior you need— not only for basic 
programming tasks (classes to provide basic math functions, arrays, strings, and so on), but also 
for graphics and networking behavior. In many cases, the] ava class libraries may be enough so 
that all you have to do in your J ava program is create a single class that uses the standard class 
libraries. For complicated Java programs, you may have to create a whole set of classes with 
defined interactions between them. 


NEWe- A classlibrary is a set of classes. 
TERM 


Behavior and Attributes 


Every class you write in J avais generally made up of two components: attributes and behavior. 
In this section, you'll learn about each oneas it applies to a thoeretical class called motorcycle. 
To finish up this section, you'll create the Java code to implement a representation of a 
motorcycle. 


Attributes 


Attributes aretheindividual thingsthat differentiateoneobject from another and determinethe 
appearance, state, or other qualities of that object. Let’s create a theoretical class called 
Motorcycle. T he attributes of a motorcycle might include the following: 


Color: red, green, silver, brown 
Style cruiser, sport bike, standard 
M ake: H onda, BM W, Bultaco 


Attributes of an object can also includeinformation about its state for example, you could have 
features for engine condition (off or on) or current gear selected. 


Attributes are defined by variables; in fact, you can consider them analogousto global variables 
for the entire object. Because each instance of a class can have different values for its variables, 
each variable is called an instance variable. 


NEWee- !nstancevariablesdefinethe attributes of an object. T heclass defines the kind of attribute, 
TERM and each instance stores its own value for that attribute. 


Each attribute, asthe term is used here, hasa single corresponding instance variable, changing 
the value of a variable changes the attribute of that object. Instance variables may be set when 
an object is created and stay constant throughout the life of the object, or they may be ableto 
change at will as the program runs. 
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In addition to instance variables, there are also class variables, which apply to the class itself and 
to all its instances. Unlike instance variables, whose values are stored in the instance, class 
variables’ values are stored in theclass itself. You'll learn about class variables later on this week; 
you'll learn more specifics about instance variables tomorrow. 


B ehavior 


A class's behavior determines what instances of that class do when their internal state changes 
or when that instance is asked to do something by another class or object. Behavior is the way 
objects can do anything to themselves or have anything doneto them. For example, to go back 
to thetheoretical motorcycle class, herearesomebehaviorsthat themotorcycle Classmight have: 
Start the engine 

Stop the engine 

Speed up 

Change gear 

Stall 

T o define an object’s behavior, you create methods, which look and behave just like functions 


in other languages, but are defined inside a class. Java does not have functions defined outside 
classes (as C ++ does). 


NEWee Mdhods are functions defined inside classes that operate on instances of those classes. 
TERM 


M ethods don’t always affect only a single object; objects communicate with each other using 
methods as well. A class or object can call methodsin another class or object to communicate 
changes in the environment or to ask that object to change its state. 


Just as there are instance and class variables, there are also instance and class methods. Instance 
methods (which areso common they're usually just called methods) apply and operate on an 
instance classmethodsapply and operateon aclass(or on other objects). You'll learn moreabout 
class methods later on this week. 


Creating a Class 


Uptothispoint, today’slesson hasbeen pretty theoretical. In thissection, you'll createa working 
example of the motorcycle Class so that you can see how instance variables and methods are 
defined in a class. You'll also create a Java application that creates a new instance of the 
Motorcycle Class and shows its instance variables. 
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Note: |’m not going to go into alot of detail about the actual syntax of this 
example here. D on’t worry too much about it if you’re not really sure what’s going 
on; it will become clear to you later on this week. All you really need to worry 
about in this example is understanding the basic parts of this class definition. 


Ready? Let's start with a basic class definition. O pen up that editor and enter the following: 


class Motorcycle { 


} 


Congratulations! Y ou’venow created aclass. O f course, it doesn’t do very much atthemoment, 
but that’s a J ava class at its very simplest. 


First, let’s create some instance variables for this class— three of them, to be specific. J ust below 
the first line, add the following three lines: 

String make; 

String color; 

boolean engineState; 

H ere, you've created three instance variables: two, make and color, Can contain string objects 
(String is part of that standard class library mentioned earlier). The third, enginestate, iS a 
boolean that refers to whether the engine is off or on. 


Technical Note: boolean in Javaisa real data type that can have the value true or 
false. UnlikeC, booleans arenot numbers. You'll hear about this again tomorrow 
so you won’t forget. 


N ow let’s add some behavior (methods) to the class. T here areall kinds of things a motorcycle 
can do, but to keep things short, let’s add just one method— a method that starts the engine. 
Add the following lines below the instance variables in your class definition: 


void startEngine() { 


if (engineState == true) 
System.out.printin("The engine is already on."); 
else { 


engineState = true; 
System.out.println("The engine is now on."); 


} 
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The startEngine method tests to see whether the engine is already running (in the line 
engineState == true) and, if itis, merely printsamessageto that effect. If theengineisn’t already 
running, it changes the state of the engine to true and then prints a message. 


With your methods and variables in place, save the program to a file called M otorcyclejava 
(remember, you should always name your J ava files the same names as the class they define). 
H ere’s what your program should look like so far: 


class Motorcycle { 
String make; 
String color; 
boolean engineState; 


void startEngine() { 


if (engineState == true) 
System.out.println("The engine is already on."); 
else { 


engineState = true; 
System.out.printin("The engine is now on."); 


Tip: T he indentation of each part of the class isn’t important to the] ava compiler. 
Using some form of indentation, however, makes your class definition easier for 
you and for other people to read. T he indentation used here, with instance vari- 
ables and methods indented from the class definition, is the style used throughout 
this book. T he] ava class libraries use a similar indentation. You can choose any 
indentation style that you like. 


Before you compile this class, let’s add one more method. The showatts method prints the 
current values of the instance variables in an instance of your Motorcycle Class. H ere’s what it 
looks like: 


void showAtts() { 
System.out.printlin("This motorcycle is a " 
+ color + " " + make); 
if (engineState == true) 
System.out.printin("The engine is on."); 
else System.out.printin("The engine is off."); 


T heshowatts method printstwo linesto thescreen: themake and color of themotorcycleobject, 
and whether or not the engine is on or off. 
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Save that file again and compile it using javac: 


javac Motorcycle.java 


Note: After this point, I’m going to assume you know how to compile and run Java 
programs. | won't repeat this information after this. 


W hat happensif you now usethe] ava interpreter to run thiscompiled class?T ry it. J avaassumes — 
that this class isan application and looks for a main method. T hisis just a class, however, so it 
doesn’t have a main method. T he] ava interpreter (java) gives you an error like this one: 


In class Motorcycle: void main(String argv[]) is not defined 


To do something with the M otorcycle class— for example, to create instances of that class and 
play with them— you're going to need to create a J ava application that uses this class or add a 
main method to this one. For simplicity’s sake, let’s do the latter. Listing 2.1 shows the main() 
method you'll add to the motorcycle Class (you'll go over what this doesin a bit). 


Type Listing 2.1. The main() method for Motorcycle. java. 


1: public static void main (String args[]) { 

2: Motorcycle m = new Motorcycle(); 

3 m.make = "Yamaha RZ350"; 

4: m.color = "yellow"; 

5: System.out.printin("Calling showAtts..."); 
6: m.showAtts() ; 

7: System.out.printin("-------- a 

8: System.out.printin("Starting engine..."); 
9: m.startEngine(); 
10: System.out.printin("-------- ie 
11: System.out.printin("Calling showAtts..."); 
12: m.showAtts() ; 
13: System.out.printin("-------- a 
14: System.out.printin("Starting engine..."); 
15: m.startEngine(); 
16:} 


With the main() method, the motorcycle class is now an application, and you can compile it 
again and this time it'll run. H ere’s how the output should look: 


JA. wp Calling showAtts... 
Output This motorcycle is a yellow Yamaha RZ350 
| ~~? The engine is off. 
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Starting engine... 
The engine is now on. 


Calling showAtts... 
This motorcycle is a yellow Yamaha RZ350 
The engine is on. 


Starving engine... 
The engine is already on. 
| m™ Thecontentsof themain() method areall goingto look very new to you, so let’sgo through 
ANAVSS it ineby lineso that you at least havea basic idea of what it does (you'll get details about 
the specifics of all of this tomorrow and the day after). 


Thefirst linedeclaresthemain() method. T hemain() method alwayslookslikethis; you'll learn 
the specifics of each part later this week. 


Line 2, Motorcycle m = new Motorcycle(), Creates anew instance of the motorcycle class and 
stores areferenceto it in the variablem. Remember, you don’t usually operate directly on classes 
in your J ava programs; instead, you create objects from those classes and then modify and call 
methods in those objects. 


Lines3 and 4 set theinstancevariablesfor thismotorcycleobject: themakeisnow ayamaha RZ350 
(avery pretty motorcycle from the mid-1980s), and the color is yel1ow. 


Lines 5 and 6 call the showAtts() method, defined in your motorcycle object. (Actually, only 
6 does; 5 just prints amessage that you're about to call thismethod.) Thenew motorcycleobject 
then printsout thevaluesof itsinstancevariables— themake and color asyou set in the previous 
lines— and shows that the engine is off. 


Line 7 prints a divider line to the screen; this is just for prettier output. 


Line9 callsthe startEngine() method in the motorcycle object to start the engine. T he engine 
should now be on. 


Line 12 prints the values of the instance variables again. This time, the report should say the 
engine is now on. 


Line 15 triesto start the engine again, just for fun. Becausethe engineis already on, this should 
print the error message. 


Inheritance, Interfaces, and Packages 


N ow that you have a basic grasp of classes, objects, methods, variables, and how to put it all 
together in aJ ava program, it’stimeto confuse you again. Inheritance, interfaces, and packages 
areall mechanisms for organizing classes and class behaviors. T he] avaclasslibraries use all these 
concepts, and thebest classlibrariesyou writefor your own programswill also usetheseconcepts. 
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Inheritance 


Inheritanceisoneof themost crucial conceptsin object-oriented programming, and it hasavery 
direct effect on how you design and writeyour J ava classes. I nheritanceisa powerful mechanism 
that means when you writea class you only haveto specify how that classis different from some 
other class, while also giving you dynamic access to the information contained in those other 
Classes. 


NEWe Withinheritance, all classes— thoseyou write, thosefrom other classlibrariesthat you use, 
TERM. and those from the standard utility classes as well— are arranged in a strict hierarchy (see 
Figure 2.2). 


Each class has a superclass (the class above it in the hierarchy), and each class can have one or 
more subclasses (classes below that classin thehierarchy). Classes further down in thehierarchy 
are said to inherit from classes further up in the hierarchy. 


Figure 2.2. 
A classhiera rchy. Class A * Class A is the superclass of B 
* Class B is a subclass of A 
* Class B is the superclass 
of C, D, and E 
* Classes C, D, and E 
are subclasses of B 


Class B 


Class C Class D Class E 


Subclassesinherit all themethodsand variablesfrom their superclasses— thatis, in any particular 
class, if thesuperclassdefines behavior that your classneeds, you don’t haveto redefineit or copy 
that codefrom some other class. Your class automatically gets that behavior from its superclass, 
that superclass gets behavior from its superclass, and so on all the way up the hierarchy. Your 
class becomes a combination of all the features of the classes above it in the hierarchy. 


Atthetop of the] avaclasshierarchy istheclassob ject; all classesinherit from thisone superclass. 
Object isthe most general class in the hierarchy; it defines behavior specific to all objectsin the 
Java class hierarchy. Each class farther down in the hierarchy adds more information and 
becomes more tailored to a specific purpose. In this way, you can think of aclass hierarchy as 
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defining very abstract concepts at the top of the hierarchy and those ideas becoming more 
concrete the farther down the chain of superclasses you go. 


M ost of thetimewhen you write new J ava classes, you'll want to create a class that has all the 
information some other class has, plus some extra information. For example, you may want a 
version of aButton with its own built-in label. T o get all the Button information, all you have 
to do isdefineyour classto inherit from Button. Your classwill automatically get all thebehavior 
defined in Button (and in Button’s superclasses), so all you have to worry about are the things 
that make your class different from Button itself. T hismechanism for defining new classes asthe 
differences between then and their superclasses is called subclassing. 


NEWee Subclasing involves creating a new class that inherits from some other class in the class 
TERM hierarchy. U sing subclassing, you only need to define the differences between your class 
and its parent; the additional behavior is all available to your class through inheritance. 


W hat if your class defines entirely new behavior, and isn’t really a subclass of another class? Y our 
class can also inherit directly from object, which still allows it to fit neatly into the J ava class 
hierarchy. In fact, if you create a class definition that doesn’t indicate its superclass in the first 
line, J avaautomatically assumesyou’reinheritingfrom object. T hemotorcycie Classyou created 
in the previous section inherited from object. 


Creating a Class Hierarchy 


If you're creating a larger set of classes, it makes sense for your classes not only to inherit from 
the existing class hierarchy, but also to make up a hierarchy themselves. T his may take some 
planning beforehand when you're trying to figure out how to organize your J ava code, but the 
advantages are significant once it’s done: 


"| When you develop your classes in a hierarchy, you can factor out information com- 
mon to multiple classes in superclasses, and then reuse that superclass’s information 
over and over again. Each subclass gets that common information from its superclass. 


() Changing (or inserting) a class further up in the hierarchy automatically changes the 
behavior of the lower classes— no need to change or recompile any of the lower 
classes, because they get the new information through inheritance and not by copying 
any of the code. 


For example, let’s go back to that Motorcycle Class, and pretend you created aj ava program to 
implement all the features of a motorcycle It’sdone, it works, and everything isfine. N ow, your 
next task is to create a J ava class called car. 


Car and Motorcycle have many similar features— both are vehicles driven by engines. Both 
havetransmissions and headlamps and speedometers. So, your first impulse may beto open up 
your Motorcycle Class file and copy over alot of the information you already defined into the 
new class car. 
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A far better plan isto factor out the common information for car and Motorcycle into amore 
general classhierarchy. T hismay bealot of work just for theclassesmotorcycle and car, butonce 
you add Bicycle, Scooter, Truck, and so on, having common behavior in areuseable superclass 
significantly reduces the amount of work you have to do overall. 


Let's design aclasshierarchy that might servethis purpose. Starting at thetop isthe classobj ect, 
which is the root of all Java classes. The most general class to which motorcycle and car both 
belong might be called vehicie. A vehicle, generally, is defined as athing that propels someone 
from one place to another. In the vehicle class, you define only the behavior that enables 
someone to be propelled from point ato point b, and nothing more. 


Below vehicle? How about two classes: personPoweredVehicle and EnginePoweredVehicle? 
EnginePoweredVehicle is different from vehicle because is has an engine, and the behaviors 
might include stopping and starting theengine, having certain amounts of gasoline and oil, and 
perhaps the speed or gear in which the engineis running. Person-powered vehicles have some 
kind of mechanism for translating people motion into vehicle motion— pedals, for example. 
Figure 2.3 shows what you have so far. 


Figure 2.3. 
T he basc vehicle hierarchy. 


Object 


Vehicle 


PersonPoweredVehicle EnginePoweredVehicle 


N ow, let’s become even more specific. With EnginePoweredVvehicle, you might have several 
Classes: Motorcycle, Car, Truck, and so on. Or you can factor out still more behavior and have 
intermediate classes for Twowneeled and Fourwheeled vehicles, with different behaviors for each 
(see Figure 2.4). 


Finally, with asubclass for the two-wheeled engine- powered vehicles you can finally havea class 
for motorcycles. Alternatively, you could additionally define scooters and mopeds, both of 
which aretwo-wheeled engine powered vehicles but have different qualities from motorcycles. 


W here do qualities such as make or color comein? W herever you want them to go— or, more 
usually, where they fit most naturally in the class hierarchy. You can definethe make and color 
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ON Vehicle, and all thesubclasses will havethosevariables as well. T he point to renember isthat 
you have to define a feature or a behavior only once in the hierarchy; it’s automatically reused 
by each subclass. 


Figure 2.4, 
wheeled vehicles. 


TwoWheeled 
EnginePoweredVehicle 


FourWheeled 
EnginePoweredVehicle 


Motorcycle Scooter 


H ow Inheritance Works 


H ow doesinheritancework?H ow isit that instances of one class can automatically get variables 
and methods from the classes further up in the hierarchy? 


For instance variables, when you createanew instanceof aclass, you get a “slot” for each variable 
defined in the current class and for each variable defined in all its superclasses. In this way, all 
the classes combine to form a template for the current object and then each object fillsin the 
information appropriate to its situation. 


M ethods operate similarly: new objects have access to all the method names of its class and its 
superclasses, but method definitions are chosen dynamically when a method is called. T hat is, 
if you call amethod on a particular object, J ava first checks the object’s class for the definition 
of that method. If it’s not defined in the object’s class, it looks in that class’s superclass, and so 
on up the chain until the method definition is found (see Figure 2.5). 


T hingsget complicated when asubclass definesamethod that hasthesamesignature(nameand 
number and type of arguments) as a method defined in a superclass. In this case, the method 
definition that is found first (starting at the bottom and working upward toward the top of the 
hierarchy) is the one that is actually executed. Because of this, you can purposefully define a 
method in asubclassthat hasthesamesignatureas a method in asuperclass, which then “hides” 
the superclass’s method. T his is called overriding a method. You'll learn all about methods on 
Day7. 
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NEWe- Overidingamethod iscreatinga method in asubclassthat hasthesamesignature(name, 
TERM_ numbe and typeof arguments) asa method in asuperclass. T hat new method then hides 
the superclass’s method (see Figure 2.6). 


Figure 2.6. 
Overriding methods. 


Method is overridden 
by this definition 


Initial method 
definition 


Message sent to object and 
passed up class hierarchy 
until a definition is found 
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Single and Multiple Inheritance 


Java's form of inheritance, as you learned in the previous sections, is called single inheritance. 
Singleinheritance means that each J ava class can have only one superclass (although any given 
superclass can have multiple subclasses). 


In other object-oriented programming languages, such as C ++ and Smalltalk, classes can have 
more than one superclass, and they inherit combined variables and methods from all those 
classes. T his is called multiple inheritance. M ultiple inheritance can provide enormous power 
in terms of being able to create classes that factor just about all imaginable behavior, but it can 
also significantly complicate class definitions and the code to produce them. Java makes 
inheritance simpler by being only singly inherited. 


Interfaces and Packages 


Java has two remaining concepts to discuss here: packages and interfaces. Both are advanced 
topics for implementing and designing groups of classes and class behavior. You'll learn about 
both interfaces and packages on D ay 16, but they are worth at least introducing here 


Recall that} avaclasseshave only asinglesuperclass, and they inherit variablesand methodsfrom 
that superclass and all its superclasses. Although single inheritance makes the relationship 
between classes and the functionality those classes implement easy to understand and to design, 
it can also be somewhat restricting—in particular, when you have similar behavior that needs 
to be duplicated across different “branches” of the class hierarchy. J ava solves this problem of 
shared behavior by using the concept of interfaces. 


NEWe Aninterfaceisacollection of method names, without actual definitions, that indicate that 
TERM. aclasshasaset of behaviorsin addition to the behaviors the class gets from itssuperclasses. 


Although a single] ava class can have only one superclass (due to single inheritance), that class 
can also implement any number of interfaces. By implementing an interface, a class provides 
method implementations (definitions) for the method names defined by the interface. If two 
very disparate classes implement the same interface, they can both respond to thesame method 
calls (as defined by that interface), although what each class actually does in response to those 
method calls may be very different. 


You don’t need to know very much about interfaces right now. You'll learn more as the book 
progresses, so if all thisis very confusing, don’t panic! 


The final new J ava concept for today is that of packages. 


NEWee- Packagesin J ava are a way of grouping together related classes and interfaces. Packages 
TERM _ enable modular groups of classes to be available only if they are needed and eliminate 
potential conflicts between class names in different groups of classes. 
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You'll learn all about packages, including how to createand usethem, in W eek 3. For now, there 
are only a few things you need to know: 


T he class libraries in the J ava D eveloper’s Kit are contained in a package called java. 

T he classes in the java package are guaranteed to be available in any Javaimplenenta- 
tion, and are the only classes guaranteed to be available across different implenenta- 
tions. The java package itself contains other packages for classes that define the 
language itself, the input and output classes, some basic networking, and the window 
toolkit functions. Classes in other packages (for example, classes in the sun or netscape 
packages) may be available only in specific implementations. 


By default, your J ava classes have access to only the classes in java.lang (the base 
language package inside the java package). T o use classes from any other package, you 
have to either refer to them explicitly by package name or import them in your source 
file 


_] To refer to a class within a package, list all the packages that class is contained in and 
the class name, all separated by periods (.). For example, take the color class, which is 
contained in the awt package (awt stands for Abstract W indowing T oolkit). T he awt 
package, in turn, is inside the java package. T o refer to the color classin your pro- 
gram, you use the notation java.awt.Color. 


Creating a Subclass 


To finish up today, let’s create a class that is a subclass of another class and override some 
methods. You'll also get a basic feel for how packages work in this example 


Probably the most typical instance of creating a subclass, at least when you first start 
programmingin Java, isin creatingan applet. All applets aresubclasses of theclassappiet (which 
ispart of the java. applet package). By creating a subclass of Applet, you automatically get all 
thebehavior from thewindow toolkit and thelayout classesthat enables your applet to bedrawn 
in the right place on the page and to interact with system operations, such as keypresses and 
mouse clicks. 


In this example, you'll create an applet similar to the H ello W orld applet from yesterday, but 
one that drawsthexe1io stringin alarger font and adifferent color. T o start this example, let’s 
first construct the class definition itself. Remember the HTML and classes directories you 
created yesterday? L et’sgo back to those, go back to your text editor, and enter thefollowingclass 
definition: 

public class HelloAgainApplet extends java.applet.Applet { 

} 

Here, you're creating a class called HelloAgainApplet. Note the part that says extends 
java.applet.Applet— that’s the part that says your applet class is a subclass of the applet Class. 
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N ote that because the Applet class is contained in the java.applet package, you don’t have 
automatic access to that class, and you have to refer to it explicitly by package and class name. 


The other part of this class definition is the public keyword. Public means that your class is 
available to the] ava system at large onceit isloaded. M ost of the time you need to makeaclass 
public only if you want it to bevisibleto all the other classesin your J ava program; but applets, 
in particular, must bedeclared to bepublic. (You'll learn more about public classesin W eek 3.) 


A class definition with nothing in it doesn’t really have much of a point; without adding or 
overriding any of its superclasses’ variables or methods, there's no point to creating a subclass 
at all. Let's add some information to this class to make it different from its superclass. 


First, add an instance variable to contain a Font object: 
Font f = new Font("TimesRoman",Font.BOLD, 36) ; 


The + instance variable now contains a new instance of the class Font, part of the java. awt 
package. T his particular font object is a Times Roman font, boldface, 36 points high. In the 
previous H ello W orld applet, the font used for the text was the default font: 12 point Times 
Roman. Using afont object, you can change the font of the text you draw in your applet. 


By creating an instance variableto hold this font object, you makeit available to all the methods 
in your class. N ow let’s create a method that uses it. 


W hen you writeapplets, thereare several “standard” methods defined in theapplet superclasses 
that you will commonly override in your applet class. T hese include methods to initialize the 
applet, to start it running, to handle operations such as mouse movements or mouse clicks, or 
to clean up when the applet stops running. One of those standard methods is the paint () 
method, which actually displaysyour applet on screen. T hedefault definition of paint) doesn’t 
do anything— it’san enpty method. By overriding paint (), you tell theapplet just what to draw 
on the screen. H ere’s a definition of paint(): 
public void paint(Graphics g) { 

g.setFont(f); 

g.setColor(Color.red) ; 

g.drawString("Hello again!", 5, 25); 
} 
T herearetwo thingsto know about thepaint () method. First, notethat thismethod isdeclared 
public, just as the applet itself was. The paint() method is actually public for a different 
reason— becausethe method it’soverridingisalso pub1ic. If you try to overrideamethod in your 
own Class that’s public in a superclass, you get a compiler error, so the public is required. 


Secondly, note that the paint () method takes a single argument: an instance of the Graphics 
class. T he Graphics Class provides platform-independent behavior for rendering fonts, colors, 
and basic drawing operations. You'll learn alot more about thecraphics classin W eek 2, when 
you create more extensive applets. 


Inside your paint() method, you’ve done three things: 


You've told the graphics object that the default drawing font will be the one contained 
in the instance variable r. 


You've told the graphics object that the default color is an instance of the color class 
for the color red. 

[] Finally, you’ve drawn your "Hello Again!" string onto the screen itself, at the x and y 
positions of 5 and 25. Thestring will be rendered in the default font and color. 


For an applet this simple, thisis all you need to do. H ere’s what the applet looks like so far: 
public class HelloAgainApplet extends java.applet.Applet { 


Font f = new Font("TimesRoman" ,Font.BOLD, 36) ; 


public void paint(Graphics g) { 
g.setFont(f) ; 
g.setColor(Color.red) ; 
g.drawString("Hello again!", 5, 50); 
} 
} 
If you've been paying attention, you'll notice something is wrong with this example up to this 
point. If you don’t know what it is, try saving this file (remember, save it to the same name as 
the class: H elloAgainApplet.java) and compiling it using the J ava compiler. You should get a 
bunch of errors similar to this one 


HelloAgainApplet.java:7: Class Graphics not found in type declaration. 


W hy are you getting these errors? Because the classes you're referring to are part of a package. 
Remember that the only package you have access to automatically is java. lang. You referred to 
the Applet class in the first line of the class definition by referring to its full package name 
(java.applet.Applet). Further on in the program, however, you referred to all kinds of other 
Classes as if they were already available. 


T here are two ways to solve this problem: refer to all external classes by full package name or 
import theappropriateclassor packageat thebeginning of your classfile. W hich oneyou choose 
to do is mostly a matter of choice, although if you find yourself referring to a classin another 
package lots of times, you may want to import it to cut down on the amount of typing. 


Inthisexample, you'll import theclasses you need. T herearethreeof them: Graphics, Font, and 
Color. All three are part of thejava.awt package H erearethelinesto import these classes. T hese 
lines go at the top of your program, before the actual class definition: 

import java.awt.Graphics; 


import java.awt.Font; 
import java.awt.Color; 
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(*) in place of a specific class name. For example, to import all the classes in the awt 


ual Tip: You also can import an entire package of (pub1ic) classes by using an asterisk 
package, you can use this line: 


import java.awt.*; 


N ow, with the proper classes imported into your program, H eloAgainApplet should compile 
cleanly to aclassfile. To test it, createan H T ML filewith the<appLet> tag as you did yesterday. 
Here's an HTML file to use: 

<HTML> 

<HEAD> 

<TITLE>Another Applet</TITLE> 

</HEAD> 

<BODY> 

<P>My second Java applet says: 

<APPLET CODE="HelloAgainApplet.class" WIDTH=200 HEIGHT=50> 

</APPLET> 

</BODY> 

</HTML> 

For thisHTML example, your Java class fileisin the same directory asthisH TML file. Save 
thefileto H eloAgainApplet.html and fireup your | ava-aware browser or the] avaapplet viewer. 
Figure 2.7 shows the result you should be getting (the H ello Again string is red). 


Figure 2.7. My second Jaws apglet say 


TheH ello Again applet. Hello Again! 


Summary 


If thisisyour first encounter with object-oriented programming, alot of theinformation in this 
chapter isgoingto seem really theoretical and overwhelming. Fear not— thefurther alongin this 
book you get, and the more] ava applications you create, the easier it is to understand. 


O neof the biggest hurdles of object-oriented programming is not necessarily the concepts, it’s 
their names. O OP has lots of jargon surrounding it. To summarize today’s material, here's a 
glossary of terms and concepts you learned today: 
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Class A template for an object, which contains variables and methods representing 
behavior and attributes. Classes can inherit variables and methods from other classes. 


O bject: A concrete instance of some class. M ultiple objects that are instances of the 
same class have access to the same methods, but often have different values for their 
instance variables. 


Instance: The same thing as an object; each object is an instance of some class. 
Superclass A class further up in the inheritance hierarchy than its child, the subclass. 


Subclass: A class lower in the inheritance hierarchy than its parent, the superclass. 
When you create a new class, that’s often called subclassing. 


Instance method: A method defined in a class, which operates on an instance of that 
Class. Instance methods are usually called just methods 


Class method: A method defined in aclass, which can operate on the class itself or on 
any object. 

Instance variable A variable that is owned by an individual instance and whose value is 
stored in the instance. 


Class variable A variable that is owned by the class and all its instances as a whole, and 
is stored in the class. 


Interface: A collection of abstract behavior specifications that individual classes can 
then implement. 


Package A collection of classes and interfaces. Classes from packages other than 
java.lang must be explicitly imported or referred to by full package name. 


Q&A 


Q Methods are effectively functions that are defined inside classes. If they look like 
functions and act like functions, why aren’t they called functions? 


A Some object-oriented programming languages do call then functions (C + calls them 
member functions). O ther object-oriented languages differentiate between functions 
inside and outside a body of a class or object, where having separate terms is impor- 
tant to understanding how each works. Because the difference is relevant in other 
languages, and because the term method is now in such common use in object- 
oriented technology, J ava uses the word as well. 

Q_ | understand instance variables and methods, but not class variables and 
methods. 

A Most everything you do in aJava program will be with objects. Some behaviors and 
attributes, however, make more sense if they are stored in the class itself rather than in 
the object. For example, to create a new instance of aclass, you need a method that is 
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defined for the class itself, not for an object. (O therwise, how can you create an 
instance of class? You need an object to call the new method in, but you don’t have an 
object yet.) Class variables, on the other hand, are often used when you have an 
attribute whose value you want to share with the instances of a class. 


M ost of the time, you'll use instance variables and methods. You'll learn more about 
class variables and methods later on this week. 
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On Days 1 and 2, you learned about Java programming in very broad terms— what a J ava 
program and an executable look like, and how to createsimpleclasses. F or the remainder of this 
week, you’re going to get down to details and deal with the specifics of what the} ava language 
looks like. 


T oday, you won't define any classes or objects or worry about how any of them communicate 
insideaJ avaprogram. Rather, you'll draw closer and examinesimple] avastatements— thebasic 
things you can do in Java within amethod definition such as main(). 


T oday you'll learn about the following: 


Java statements and expressions 
Variables and data types 
Comments 

Literals 

Arithmetic 

Comparisons 

Logical operators 


Technical N ote: J ava looks a lot like C++, and— by extension—likeC. M uch of 
the syntax will be very familiar to you if you are used to working in these languages. 
If you are an experienced C or C++ programmer, you may want to pay special 
attention to the T echnical N otes (such as this one), because they will provide 
information about the specific differences between these and other traditional 
languages and J ava. 


Statements and E xpressions 


A statement is the simplest thing you can do in J ava; astatement formsa single] ava operation. 
All the following are simple J ava statements: 
int i = 1; 
import java.awt.Font; 
System.out.println("This motorcycle is a " 

+ color + " " + make); 
m.engineState = true; 
Statements sometimes return values— for example, when you add two numbers together or test 
to see whether one value is equal to another. T hese kind of statements are called expressions. 
W e'll discuss these later on today. 


The most important thing to renember about J ava statements is that each one ends with a 
semicolon. Forget the semicolon and your Java program won't compile. 


Javaalso hascompound statements, or blocks, which can beplaced wherever a single statement 
can. Block statements are surrounded by braces(}). You'll learn more about blocksin C hapter 
5, “Arrays, Conditionals, and Loops.” 


Variables and D ata Types 


Variables are locationsin memory in which values can be stored. T hey haveaname, atype, and 
a value. Before you can use a variable, you have to declare it. After it is declared, you can then 
assign values to it. 


Java actually has three kinds of variables: instance variables, class variables, and local variables. 


Instance variables, as you learned yesterday, are used to define attributes or the state for a 
particular object. Class variables are similar to instance variables, except their values apply to all 
that class’s instances (and to the class itself) rather than having different values for each object. 


Local variables aredeclared and used insidemethod definitions, for example, for index counters 
in loops, as temporary variables, or to hold values that you need only inside the method 
definition itself. T hey can also beused insideblocks( {}), which you'll learn about later this week. 
O ncethemethod (or block) finishesexecuting, thevariabledefinition and its value ceaseto exist. 
U selocal variablesto storeinformation needed by asinglemethod and instance variablesto store 
information needed by multiple methods in the object. 


Although all three kinds of variables are declared in much the same ways, class and instance 
variables are accessed and assigned in slightly different ways from local variables. T oday, you'll 
focus on variables as used within method definitions; tomorrow, you'll learn how to deal with 
instance and class variables. 


Note: U nlike other languages, J] ava does not have global variables— that is, vari- 
ables that are global to all parts of a program. Instance and class variables can be 
used to communicate global information between and among objects. Renember, 
Java is an object-oriented language, so you should think in terms of objects and 
how they interact, rather than in terms of programs. 


D eclaring Variables 


To useany variablein aJ ava program, you must first declareit. V ariable declarations consist of 
a type and a variable name: 
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int myAge; 
String myName; 
boolean isTired; 
Variable definitions can go anywherein amethod definition (that is, anywhere a regular J ava 
statement can go), although they aremost commonly declared at the beginning of thedefinition 
before they are used: 
public static void main (String args+]) { 
int count; 


String title; 
boolean isAsleep; 


i 
You can string together variable names with the same type: 


int x, y, Z; 
String firstName, LastName; 


You can also give each variable an initial value when you declare it: 


int myAge, mySize, numShoes = 28; 

String myName = "Laura"; 

boolean isTired = true; 

int a= 4, b = 5, c = 6; 

If there are multiple variables on the same line with only one initializer (as in the first of the 
previousexamples), theinitial valueappliesto only thelast variablein adeclaration. You can also 
group individual variables and initializers on the same line using commas, as with the last 
example, above. 


Local variablesmust be given valuesbeforethey can beused (your J avaprogram will not compile 
if you try to usean unassigned local variable). F or this reason, it’sa good idea alwaysto givelocal 
variables initial values. Instance and class variable definitions do not have this restriction (their 
initial value depends on the type of the variable: nui for instances of classes, @ for numeric 
variables, '\@' for characters, and false for booleans). 


Notes on Variable Names 


Variablenamesin J avacan start with aletter, an underscore (_), or adollar sign ($). T hey cannot 
start with a number. After the first character, your variable names can include any letter or 
number. Symbols, such ass, *, e, and so on, areoften reserved for operatorsin J ava, so be careful 
when using symbols in variable names. 


In addition, the Java language uses the Unicode character set. Unicode is a character set 
definition that not only offers characters in the standard ASCII character set, but also several 
million other characters for reoresenting most international alphabets. T hismeansthat you can 


useaccented charactersand other glyphsaslegal charactersin variablenames, aslongasthey have 
a Unicode character number above oace. 


characters. If you don’t understand U nicode, or don’t think you havea use for it, 
a it’s safest just to use plain numbers and letters in your variable names. You'll learn a 
little more about U nicode later on. 


\ Caution: T he U nicode specification is a two-volume set of lists of thousands of 


Finally, note that the J ava language is case-sensitive, which means that uppercase letters are 
different from lowercase letters. T his means that the variable x is different from the variable x, 
and arose isnot arose isnot arose. K eep thisin mind as you write your own J ava programs 
and as you read J ava code other people have written. 


By convention, Java variables have meaningful names, often made up of several words 
combined. T he first word is lowercase, but all following words have an initial uppercase letter: 
Button theButton; 


long reallyBigNumber; 
boolean currentWeatherStateOfPlanetXShortVersion; 


Variable Types 


In addition to the variablename, each variabledeclaration must havea type, which defines what 
values that variable can hold. T he variable type can be one of three things: 


One of the eight basic primitive data types 
Thename of a class 
An array 


You'll learn about how to declare and use array variables in Chapter 5. 


The eight primitive data types handle common types for integers, floating-point numbers, 
characters, and boolean values (true or false). T hey’recalled primitive because they're built into 
the system and are not actual objects, which makesthem more efficient to use. N ote that these 
data types are machineindependent, which means that you can rely on their sizes and 
characteristics to be consistent across your J ava programs. 


T herearefour J avainteger types, each with different ranges of values(aslisted in T able3.1). All 
are signed, which means they can hold either positive or negative numbers. W hich type you 
choose for your variables depends on the range of values you expect that variable to hold; if a 
value becomes too big for the variable type, it is truncated. 
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Table 3.1. Integer types. 
Type _ Size Range 
byte 8 bits -128 to 127 
short 16 bits --32,768 to 32,767 
int 32 bits  -2,147,483,648 to 2,147,483,647 
long 64 bits  -9223372036854775808 to 9223372036854775807 


Floating-point numbers areused for numberswith a decimal part. J avafloating-point numbers 
are compliant with IEEE 754 (an international standard for defining floating-point numbers 
and arithmetic). T herearetwo floating-point types: f1oat (32 bits, single precision) and double 
(64 bits, double precision). 

T hechar typeisused for individual characters. Because} ava usestheU nicodecharacter set, the 
char type has 16 bits of precision, unsigned. 

Finally, the boolean type can have one of two valués, true or false. N ote that unlikein other 


C-like languages, boolean is not a number, nor can it be treated as one. All tests of boolean 
variables should test for true Or false. 


In addition to theeight basic datatypes, variablesin J avacan also be declared to hold an instance 
of a particular class: 


String LastName; 
Font basicFont; 
OvalShape myOval; 


Each of these variables can then hold only instances of the given class. As you create new classes, 
you can declare variables to hold instances of those classes (and their subclasses) as well. 


Technical N ote: J ava does not have a typedef statement (asin C and C+). To 
declare new typesin Java, you declare a new class; then variables can be declared to 
be of that class's type. 


Assigning Values to Variables 


O nceavariablehasbeen declared, you can assign a valueto that variableby using theassignment 
operator =: 


size = 14; 
tooMuchCaffiene = true; 
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Comments 


Javahasthreekinds of comments. /* and */ surround multiline comments, asin C or C++ All 
text between the two delimiters is ignored: 
/* I don't know how I wrote this next part; I was working 

really late one night and it just sort of appeared. I 

suspect the code elves did it for me. It might be wise 


not to try and change it. 
5) 


Comments cannot be nested; that is, you cannot have a comment inside a comment. 


D ouble-slashes (//) can be used for a single line of comment. All the text up to the end of the 
line is ignored: 


int vices = 7; // are there really only 7 vices? 


T hefinal type of comment begins with ;** and ends with «;. T hese are special comments that 
are used for the javadoc system. | avadoc is used to generate AP! documentation from the code. 
You won't learn about javadoc in this book; you can find out more information from the 
documentation that camewith Sun's] avaD eveloper’sK it or from Sun's] avahomepage (http: / 
/java.sun.com). 


Literals 


Literals are used to indicate simple values in your J ava programs. 


NEWeee Literal is a programming language term, which essentially means that what you type is 
TERM _ whatyou get. For example if you type4 in aJ avaprogram, you automatically get an integer 
with the value 4. If you type ‘a', you get a character with the value a. 


Literals may seem intuitive most of the time, but there are some special cases of literalsin J ava 
for different kinds of numbers, characters, strings, and boolean values. 


Number Literals 


T hereareseveral integer literals. 4, for example, isadecimal integer literal of type int (although 
you can assign it to a variable of type byte or short because it’s small enough to fit into those 
types). A decimal integer literal larger than an int isautomatically of type1ong. Y ou also can force 
asmaller number to a 10ng by appending an - or 1 to that number (for example, 4L is along 
integer of value 4). N egative integers are preceded by a minus sign— for example, -45. 


Integers can also be expressed as octal or hexadecimal: a leading a indicates that a number is 
octal— for example, 0777 or 0004. A leading ox (or ox) means that it isin hex (oxFF, @xaF4s). 
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H exadecimal numbers can contain regular digits (0-9) or upper- or lowercase hex digits (a-f or 
A-F). 


Floating-point literals usually have two parts: the integer part and the decimal part— for 
example, 5.677777. Floating-point literals result in a floating-point number of type double, 
regardless of the precision of that number. You can force the number to the type float by 
appending the letter + (or F) to that number— for example, 2.5eF. 


You can use exponents in floating-point literals using the letter e or E followed by the exponent 
(which can be a negative number): 10e45 or .36E-2. 


B oolean Literals 


Boolean literals consist of the keywordsStrue and false. T hesekeywords can beused anywhere 
you need a test or as the only possible values for boolean variables. 


Character Literals 


Character literals are expressed by a single character surrounded by singlequotes: 'a', '#', '3', 
and so on. Characters are stored as 16-bit U nicode characters. T able 3.2 lists the special codes 
that can represent nonprintable characters, as well as characters from theU nicode character set. 
Theletter a in the octal, hex, and U nicode escapes represents anumber or ahexadecimal digit 
(a-f or A-F). 


Table 3.2. Character escape codes. 


Escape Meaning 

\n N ewline 

\t Tab 

\b Backspace 

\r Carriage return 
\f Formfeed 

\\ Backslash 

\' Single quote 

i D ouble quote 
\ddd O ctal 

\xdd H exadecimal 
\udddd U nicode character 
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Technical Note: C and C++ programme's should note that J ava does not include 
character codes for \a (bell) or \v (vertical tab). 


String Literals 


A combination of characters is a string. Strings in J ava are instances of the class String. Strings 
are not simple arrays of characters as they arein C or C-H, although they do have many array- 
like characteristics (for example, you can test their length and add and delete individual 
characters as if they were arrays). Because string objects are real objects in Java, they have 
methods that enable you to combine, test, and modify strings very easily. 


String literals consist of a series of characters inside double quotes: 


"Hi, I'm a string literal." 
"//an empty string 


Strings can contain character constants such as newline, tab, and U nicode characters: 


"A string with a \t tab in it" 
"Nested strings are \"strings inside of\" other strings" 
"This string brought to you by Java\u2122" 


In the last example, the U nicode code sequence for \u2122 produces a trademark symbol (™ ). 


Note: J ust because you can represent a character using a U nicode escape does not 
mean your computer can display that character— the computer or operating system 
you are running may not support Unicode, or the font you’re using may not havea 
glyph (picture) for that character. All that U nicode escapes in J ava provide is a way 
to encode special characters for systems that support U nicode. 


W hen you useastring literal in your J ava program, J ava automatically creates an instance of the 
Classstring for you with thevalueyou giveit. Stringsareunusual in thisrespect; theother literals 
do not behave in this way (none of the primitive base types are actual objects), and usually 
creating anew object involvesexplicitly creating anew instanceof aclass. You'll learn moreabout 
strings, the String class, and the things you can do with strings later today and tomorrow. 
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Expressions and Operators 


Expressions are the simplest form of statement in J ava that actually accomplishes something. 


NEWe Expressonsare statements that return a value 
TERM O perators are special symbols that are commonly used in expressions. 


Arithmetic and tests for equality and magnitude arecommon examples of expressions. Because 
they return a value, you can assign that result to a variable or test that value in other Java 
statements. 


O perators in J ava include arithmetic, various forms of assignment, increment and decrement, 
and logical operations. T his section describes all these things. 


Arithmetic 


Java has five operators for basic arithmetic (see T able 3.3). 


Table 3.3. Arithmetic operators. 


Operator Meaning Example 
+ Addition 3+4 
- Subtraction 5-7 
* M ultiplication 5 * 5 
+ Division 14+=7 
% M odulus 20% 7 


Each operator takestwo operands, oneon either side of the operator. T he subtraction operator 
(-) can also be used to negate a single operand. 


Integer division results in an integer. Because integers don’t have decimal fractions, any 
remainder is ignored. T he expression 31 + 9, for example, resultsin 3 (9 goesinto 31 only 3 
times). 


M odulus (x) gives the remainder oncethe operands have been evenly divided. For example, 31 
% g resultsin 4 because 9 goes into 31 three times, with 4 left over. 


N ote that, for integers, the result type of most operationsis an int Or a long, regardless of the 
original typeof theoperands. Largeresultsareof typeiong; all othersare int. Arithmeticwherein 
one operand is an integer and another is a floating point results in a floating-point result. (If 
you're interested in the details of how J ava promotes and converts numeric typesfrom onetype 
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to another, you may want to check out the] ava Language Specification; that’s more detail than 
| want to cover here.) 


Listing 3.1 isan example of simple arithmetic. 


‘Type Listing 3.1. Simple arithmetic. 


1: class ArithmeticTest { 
2: public static void main (String[] args) { 


3: short x = 6; 
4: int y = 4; 
5: float a = 12.5f; 
6: float b = 7f; 
7: 
8: System.out.println("x is "+x +", yis "+ y); 
9: System.out.printin("x + y = "+ (x + y))3 
10: System.out.printin("x - y = "+ (x - y))3 
11: System.out.printin("x / y =" + (x / y))3 
12: System.out.println("x % y = "+ (x % y))3 
13: 
14: System.out.printin("a is "+a+", bis "+ b; 
15: System.out.printin("a / b =" + (a / b)); 
16: } 
17: 
18: } 
A poop xX is 6, y is 4 
Output x+v- 1 
| ~~ ) xX -yr2 
x /y=1 
Xx %y=2 
ais 12.5, b is 7 
a / b = 1.78571 


A ™ InthissimpleJ avaapplication (notethemain() method), you initially definefour variables 
nalyss in lines 3 through 6: x and y, which areintegers (type int), and a and b, which arefloating- 
point numbers (type f1oat). Keep in mind that the default type for floating-point literals 
(such as 12.5) is double, so to make sure these are numbers of type float, you have to use an ¢ 
after each one (lines 5 and 6). 


T heremainder of theprogram merely doessomemath with integers and floating point numbers 
and prints out the results. 


Thereisoneother thing to mention about this program: the method system. out.printin(). 
You've seen this method on previous days, but you haven’t really learned exactly what it does. 
The system. out.printin() method merely prints a message to the standard output of your 
systen— to thescreen, to aspecial window, or maybejust to aspecial logfile, deoendingon your 
system and the development environment you're running (Sun’s}DK prints it to the screen). 
The system. out.printin() method takes a single argument— a string— but you can use + to 
concatenate values into a string, as you'll learn later today. 
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More About Assignment 


Variable assignment is a form of expression; in fact, because one assignment expression results 
in avalue, you can string them together like this: 


X=y=ZzZ=0; 
In this example, all three variables now have the value @. 


T heright sideof an assignment expression is always evaluated beforethe assignment takes place. 
T his means that expressions such asx = x + 2do theright thing; 2 is added to the value of x, 
and then that new valueis reassigned to x. In fact, this sort of operation isso common that J ava 
has several operators to do a shorthand version of this, borrowed from C and C+. Table 3.4 
shows these shorthand assignment operators. 


Table 3.4. Assignment operators. 


Expression Meaning 
x t= y X=X+y 
x -= y X+X-yY 
x *= y X=x*y 
X += y X=X+Y 


Technical N ote: If you rely on complicated side effects of subexpressions on either 
side of these assignments, the shorthand expressions may not be entirely equivalent 
to their longhand equivalents. For more information about very complicated 
expressions, evaluation order, and side effects, you may want to consult the] ava 
Language Specification. 


Incrementing and Decrementing 


Asin C and C-H, the++ and -- operators are used to increment or decrement a value by 1. For 
example, x++ increments the value of x by 1 just asif you had used the expression x = x + 1. 
Similarly x-- decrements the value of x by 1. 


T heseincrenent and decrement operators can be prefixed or postfixed; that is, the++ or -- can 
appear beforeor after thevalueit increnents or decrements. F or simpleincrement or decrement 
expressions, which one you useisn’t overly important. In complex assignments, where you are 
assigning the result of an increment or decrement expression, which one you use makes a 
difference. 


3/2 sams 
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T ake, for example, the following two expressions: 


xt++; 
++X; 


y 
y 
T hese two expressions give very different results because of the difference between prefix and 
postfix. When you use postfix operators (x++ or x--), y gets the value of x before before x is 
incremented; using prefix, the value of x isassigned to y after theincrement hasoccurred. Listing 
3.2 isa] ava example of how all this works. 


a 


Type Listing 3.2. Test of prefix and postfix increment operators. 


class PrePostFixTest { 


: public static void main (String args[]) { 


1: 

2: 

3 

4: int x = Q; 

5: int y = 0; 

6: 

7: System.out.printin("x and y are "+x + " and" +y ); 
8: xt+; 

9: System.out.printin("x++ results in " + x); 

10: +4+X5 

11: System.out.printin("++x results in " + x); 

12: System.out.printin("Resetting x back to 0."); 

13: xX = 0; 

14: System.out.printin("—————— oe ee 

15: y = X45 

16: System.out.printin("y = x++ (postfix) results in:"); 
17: System.out.printin("x is " + x); 

18: System.out.printin("y is " + y); 

19: System.out.printin("—————— wy 
20: 
21: y = ++x; 
22: System.out.printin("y = ++x (prefix) results in:"); 
23: System.out.printin("x is " + x); 
24: System.out.printin("y is " + y); 
25: System.out.printin("—————— "3 
26: 
27: } 
28: 
29: } 


| x and y are @ and 0 
Outpu x++ results in 1 
++x results in 2 


Resetting x back to 0. 


y 

x is 1 
y 

y = ++x (prefix) results in: 
x is 2 

y is 2 
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Anel 5 In the first part of this example, you increment x alone using both prefix and postfix 
yg increment operators. In each, x isincremented by 1 each time In this simple form, using 
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either prefix OF postfix works the same way. 


In the second part of this example, you use the expression y = x++, in which the postfix 
increment operator isused. In this result, thevalueof x isincremented after that value is assigned 
to y. H encethe result: y is assigned the original value of x (a), and then x isincremented by 1. 


Inthethird part, you usethepretix expression y = ++x.H ere, thereverse occurs: x isincremented 
before its value is assigned to y. Because x is 1 from the previous step, its value is incremented 
(to 2), and then that value is assigned to y. Both x and y end up being 2. 


Technical N ote: T echnically, this description is not entirely correct. In reality, J ava 
always completely evaluates all expressions on the right of an expression before 
assigning that value to a variable, so the concept of “assigning x to y before x is 
incremented” isn’t precisely right. Instead, J ava takes the value of x and “remem- 
bers” it, evaluates (increments) x, and then assigns the original value of x to y. 
Although in most simple cases this distinction may not beimportant, for more 
complex expressions with side effects it may change the behavior of the expression 
overall. See the Language Specification for many more details about the details of 


expression evaluation in J ava. 


Comparisons 


J ava has several expressions for testing equality and magnitude. All of these expressions return 
a boolean value (that is, true or false). T able 3.5 shows the comparison operators: 


Table 3.5. Comparison operators. 


Operator Meaning Example 
= Equal x == 3 
l= N ot equal x 1= 3 

< Less than x <3 

> Greater than x >3 

< Less than or equal to x <3 

> Greater than or equal to x23 


Logical Operators 


Expressions that result in boolean values (for example, the comparison operators) can be 
combined by using logical operators that represent the logical combinations anp, or, xor, and 
logical Nor. 


For anp combinations, use either the or aa. The expression will be true only if both operands 
testsarealso true; if ether expression isfalse, theentireexpression isfalse. T hedifferencebetween 
thetwo operatorsisin expression evaluation. U sings, both sidesof the expression are evaluated 
regardless of theoutcome. U sing sa, if theleft side of the expression is false, the entireexpression 
returns false, and the right side of the expression is never evaluated. 


For or expressions, useeither | or '!. or expressionsresult in trueif ether or both of theoperands 
is also true, if both operands are false, the expression is false. As with & and aa, the single : 

evaluates both sides of the expression regardless of the outcome; with !:, if the left expression 
is true, the expression returns true and the right side is never evaluated. 


In addition, thereisthexor operator ~, which returnstrue only if its operandsare different (one 
true and one false, or vice versa) and false otherwise (even if both are true). 


In general, only the aa and |! arecommonly used as actual logical combinations. a, !, and + are 
more commonly used for bitwise logical operations. 


For not, usethe: operator with a single expression argument. T he value of the not expression 
is the negation of the expression; if x is true, !x is false 


B itwise O perators 


Finally, here's a short summary of the bitwise operatorsin J ava. These are all inherited from C 
and C ++and areused to perform operations on individual bits in integers. T his book does not 
go into bitwise operations; it’s an advanced topic covered better in books on C or C +4. Table 
3.6 summarizes the bitwise operators. 


Table 3.6. Bitwise operators. 


O perator Meaning 

& Bitwise anp 
Bitwise or 

“ Bitwise xor 

<< Left shift 

>> Right shift 

>>> Zero fill right shift 


continues 
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Table 3.6. continued 


Operator Meaning 

~ Bitwise complement 

<<= Left shift assignment (x =x <<y) 

>>= Right shift assignment (x =x >>y) 

>>>= Zero fill right shift assignment (x =x >>> y) 
X&=y AND assignment (x =x & y) 

xy or assignment (x +x | y) 

x*=y NoT assignment (x =x “y) 


Operator Precedence 


O perator precedence determines the order in which expressions are evaluated. T his, in some 
cases, can determine the overall value of the expression. For example, take the following 
expression: 


y=6+4/2 


Depending on whether thee + 4 expression or the 4 + 2 expression is evaluated first, the value 
of y can end up beings or s. O perator precedence determines the order in which expressions 
are evaluated, so you can predict the outcome of an expression. In general, increment and 
decrement are evaluated beforearithmetic, arithmetic expressions areevaluated beforecompari- 
sons, and comparisons are evaluated before logical expressions. Assignment expressions are 
evaluated last. 


T able 3.8 shows the specific precedence of the various operators in J ava. O perators further up 
in the table are evaluated first; operators on the same line have the same precedence and are 
evaluated left to right based on how they appear in the expression itself. For example, give that 
same expression y = 6 + 4 + 2, younow know, according to thistable, that division is evaluated 
before addition, so the value of y will bes. 


Table 3.7. Operator precedence. 
Operator Notes 
- 10 Parentheses () group expressions; dot (.) is used for access to 
methods and variables within objects and classes (discussed 
tomorrow); [] is used for arrays (discussed later on in the week) 
++ -- | ~ instanceof Returns true or false based on whether the object is an instance 


of the named class or any of that class's superclasses (discussed 
tomorrow) 
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O perator Notes 


new (type)expression 1h@€new operator is used for creating new instances of classes; () 
in this case is for casting a value to another type (you'll learn 
about both of these tomorrow) 


* 2% M ultiplication, division, modulus 
— Addition, subtraction 

<< >> >>> Bitwise left and right shift 
<><> Relational comparison tests 

a fis Equality 

& AND 

* XOR 

OR 

&& Logical ano 

i! Logical or 

Qe Shorthand for it...then...else (discussed on D ay 5) 
= t= -= *= t= %= *= Various assignments 

&= I= <<= >>= >>>5 


Youcan alwayschangetheorder in which expressionsare evaluated by using parentheses around 
the expressions you want to evaluate first. You can nest parentheses to make sure expressions 
evaluate in the order you want them to (the innermost parenthetical expression is evaluated 
first). The following expression resultsin avalue of 5, because thee + 4 expression is evaluated 
first, and then the result of that expression (10) is divided by 2: 


y= (6+ 4) /2 


Parentheses also can be useful in cases where the precedence of an expression isn’t immediately 
clear— in other words, they can makeyour codeeasier to read. Adding parentheses doesn’t hurt, 
so if they help you figure out how expressions are evaluated, go ahead and use then. 


String Arithmetic 


One special expression in J ava isthe use of the addition operator (+) to create and concatenate 
strings. In most of the previous examples shown today and in earlier lessons, you've seen lots of 
lines that looked something like this: 


System.out.printin(name + " is a " + color " beetle"); 


T heoutput of that line(to the standard output) isasinglestring, with the values of the variables 
(here, name and color), inserted in the appropriate spots in the string. So what’s going on here? 57 
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The + operator, when used with strings and other objects, creates a single string that contains 
theconcatenation of all itsoperands. | f any of theoperandsin string concatenation isnot astring, 
it is automatically converted to a string, making it easy to create these sorts of output lines. 


Technical Note: An object or type can be converted to a string if you implement 
the method tostring(). All objects have a default string reoresentation (the name 
of the class followed by brackets), but most classes override tostring() to providea 
more meaningful printable representation. 


String concatenation makeslinessuch as the previous one especially easy to construct. T o create 
astring, just add all thepartstogether— thedescriptionsplusthevariables— and outputitto the 
standard output, to the screen, to an applet, or anywhere 


T he += operator, which you learned about earlier, also works for strings. For example, take the 
following expression: 


myName += " Jr."; 
T his expression is equivalent to this: 
myName = myName + " Jr."; 


just as it would be for numbers. In this case, it changes the value of myname (which might be 
something like John smith to have aur. at theend (John smith ur.). 


Summary 


Asyou learned in thelast two lessons, aJ avaprogram ismadeup primarily of classes and objects. 
Classes and objects, in turn, are made up of methods and variables, and methods are made up 
of statements and expressions. It is those last two things that you've learned about today; the 
basic building blocks that enable you to create classes and methods and build them up to afull- 
fledged J ava program. 


T oday, you learned about variables, how to declare them and assign values to them; literals for 
easily creating numbers, characters, and strings; and operators for arithmetic, tests, and other 
simpleoperations. W ith thisbasic syntax, you can moveon tomorrow to learning about working 
with objects and building simple useful J ava programs. 


Tofinish up thissummary, T able3.8 isalist of all the operators you learned about today so that 
you can refer back to then. 


Table 3.8. Operator summary. 


O perator 


Meaning 


Addition 
Subtraction 

M ultiplication 
Division 

M odulus 

Less than 

Greater than 

Less than or equal to 
Greater than or equal to 
Equal 

N ot equal 

Logical anp 

Logical or 

Logical not 

AND 

OR 

XOR 

Left shift 

Right shift 

Zero fill right shift 
Complement 
Assignment 
Increment 
Decrement 

Add and assign 
Subtract and assign 
M ultiply and assign 
Divide and assign 
M odulus and assign 
AND and assign 


continues 
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Table 3.8. continued 
Operator Meaning 
t= or and assign 
<<= Left shift and assign 
>>= Right shift and assign 
>>>= Zero fill right shift and assign 


Q&A 


p> oO 


| didn’t see any way to define constants. 


You can’t create local constants in Java; you can create only constant instance and class 
variables. You'll learn how to do this tomorrow. 


W hat happens if you declare a variable to be some integer type and then give it a 
number outside the range of values that variable can hold? 


Logically, you would think that the variable is just converted to the next larger type, 
but this isn’t what happens. W hat does happen is called overflow. T his means that if a 
number becomes too big for its variable, that number wraps around to the smallest 
possible negative number for that type and starts counting upward toward Zero again. 


Because this can result in some very confusing (and wrong) results, make sure that you 
declare the right integer type for all your numbers. If there’s a chance a number will 
overflow its type, use the next larger type instead. 

H ow can you find out the type of a given variable? 

If you're using the base types (int, float, boolean), and so on, you can’t. If you care 
about the type, you can convert the value to some other type by using casting (you'll 
learn about this tomorrow). 

If you're using class types, you can use the instanceof operator, which you'll learn 
more about tomorrow. 

Why does Java have all these shorthand operators for arithmetic and assignment? 
It’s really hard to read that way. 

T he syntax of J ava is based on C-+4, and thereforeon C. Oneof C’simplicit goals is 
the capability of doing very powerful things with a minimum of typing. Because of 
this, shorthand operators, such as the wide array of assignments, are common. 

There's no rule that says you have to use these operators in your own programs, 
however. If you find your code to be more readable using the long form, no one will 
come to your house and make you changeit. 
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Let’sstart today’slesson with an obvious statement: because] avais an object-oriented language, 
you’re going to be dealing with alot of objects. You'll create them, modify them, move then 
around, change their variables, call their methods, combine them with other objects— and, of 
course, develop classes and use your own objects in the mix. 


T oday, therefore, you'll learn all about the J ava object in its natural habitat. T oday’s topics 
include: 
“| Creating instances of classes 
T esting and modifying class and instance variables in your new instance 
Calling methods in that object 
Casting (converting) objects and other data types from one class to another 
“| Other odds and ends about working with objects 
— An overview of the Java class libraries 


Creating New Objects 


W hen you write aj ava program, you define a set of classes. As you learned on D ay 2, classesare 
templatesfor objects; forthemost part, you merely usetheclassto createinstancesand then work 
with thoseinstances. In thissection, therefore, you'll learn how to create a new object from any 
given class. 


Remember strings from yesterday? Y ou learned that using a string literal— a series of characters 
enclosed in double-quotes— creates a new instance of the class string with the value of that 
string. 


The string class is unusual in that respect— although it’s a class, there’s an easy way to create 
instancesof that classusingaliteral. T heother classesdon’t havethat shortcut; to createinstances 
of those classes you have to do so explicitly by using the new operator. 


Note: W hat about the literals for numbers and characters? D on’t they create 
objects, too? Actually, they don’t. The primitive data types for numbers and 
characters create numbers and characters, but for efficiency, they aren't actually 
objects. You can put object-wrappers around them if you need to treat them like 
objects (you'll learn how to do this later). 
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Using new 
To create a new object, you use new with the name of the class you want to create an instance 
of, then parentheses after that: 


String str = new String(); 
Random r = new Random(); 
Motorcycle m2 = new Motorcycle() 


T he parentheses are important; don’t leave them off. T he parentheses can be enpty, in which 
case the most simple, basic object is created, or the parentheses can contain arguments that 
determine the initial values of instance variables or other initial qualities of that object. The 
number and type of arguments you can use with new are defined by the class itself by using a 
special method called a constructor; you'll learn about how to create constructors in your own 
Classes later on this week. 


| Caution: Some classes may not enable you to create instances without any argu- 
ments. C heck the class to make sure. 


fies 


For example, take the pate class, which creates date objects. Listing 4.1 is a] ava program that 
shows three different ways of creating a pate object using new: 


Final 
Type Listing 4.1. Laura’s pate program. 


1: import java.util.Date; 

2: 

3: class CreateDates { 

4: 

5: public static void main (String args[]) { 
6: Date d1, d2, d3; 

7: 

8: d1 = new Date(); 

9: System.out.printlin("Date 1: " + d1); 
10: 

11: d2 = new Date(71, 7, 1, 7, 30); 

12: System.out.printlin("Date 2: " + d2); 
13: 

14: d3 = new Date("April 3 1993 3:24 PM"); 
15: System.out.printlin("Date 3: " + d3); 
16: } 

17: } 


f a ©6©6©. Date: 1: Sun Nov 26 19:10:56 PST 1995 
Output Date 2: Sun Aug 01 07:30:00 PDT 1971 
‘es | Date 3: Sat Apr 03 15:24:00 PST 1993 
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Anal In this example, three different dates are created by using different arguments to new. T he 
ys first instance (line 8) uses new with no arguments, which creates a pate object for today’s 
date (as the first line of the output shows). 


The second Date object you create in this example has five integer arguments. T he arguments 
represent a date: year, month, day, hours, and seconds. And, asthe output shows, this creates 
a Date object for that particular date Sunday, August first, 1971, at 7:30 AM. 


The third version of pate takes one argument, a string, representing the date as a text string. 
W hen the date object iscreated, that string is parsed, and abate object with that date and time 
iscreated (see thethird line of output). T hedatestring can takemany different formats; see the 
API documentation for the pate class (part of the java.uti1 package) for information about 
what strings you can use. 


What new Does 


W hat doesnew do? W hen you usethenew operator, several thingshappen: first, thenew instance 
of thegiven classis created, and memory isallocated for it. In addition (and most importantly), 
when thenew object iscreated, aspecial method defined in thegiven classiscalled. T his special 
method is called a constructor. 


NEWe- Constructors are special methods for creating and initializing new instances of classes. 
TERM Constructorsinitializethenew object and itsvariables, createany other objects that object 
needs, and generally perform any other operations the object needs to run. 


M ultiple constructor definitions in a class can each have a different number or type of 
arguments— then, when you use new, you can specify different arguments in the argument list, 
and the right constructor for those arguments will be called. T hat’s how each of those different 
versions of new that were listed previously can create different things. 


When you create your own classes, you can define as many constructors as you need to 
implement that class’s behavior. You'll learn how to create constructors on D ay 7. 


A Note on Memory Management 


M emory management in J avaisdynamic and automatic. W hen you create anew object in J ava, 
Java automatically allocates the right amount of memory for that object in the heap. Y ou don’t 
have to allocate any memory for any objects explicitly; Java does it for you. 


W hat happenswhen you’ refinished with that object? H ow do you de-allocatethe memory that 
object uses? T he answer is again: memory management is automatic. O nce you finish with an 
object, that object no longer has any live references to it (it won't be assigned to any variables 
you’ restill using or stored in any arrays). J avahasagarbagecollector that looksfor unused objects 
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and reclaims thememory that those objects areusing. You don’t have to do any explicit freeing 
of memory; you just have to make sure you're not still holding onto an object you want to get 
rid of. You'll learn more specific details about the J ava garbage collector and how it works on 
Day 21. 


Accessing and Setting Class and 
Instance Variables 


N ow you haveyour very own object, and that object may haveclassor instance variables defined 
init. H ow do you work with those variables? Easy! Class and instance variables behavein exactly 
the same ways as the local variables you learned about yesterday; you just refer to them slightly 
differently than you do regular variablesin your code. 


Getting Values 
To get at the value to an instance variable, you use dot notation. 


NEWe- With dot notation, an instance or class variable name has two parts: the object on the left 
TERM sideof the dot, and the variable on the right side of the dot. 


For example, if you havean object assigned to thevariablemyobj ect, and that object hasavariable 
called var, you refer to that variable’s value like this: 


myObject.var; 


This form for accessing variables is an expression (it returns a value), and both sides of the dot 
are also expressions. T his means that you can nest instance variable access. If that var instance 
variable itself holds an object, and that object hasitsown instance variable called state, you can 
refer to it like this: 


myObject.var.state; 


D ot expressionsareevaluated left to right, so you start with myobject’Svariablevar, which points 
to another object with the variable state. You end up with the value of that state variable. 


Changing Values 


Assigning a valueto that variableis equally easy— just tack an assignment operator on theright 
side of the expression: 


myObject.var.state = true; 
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Listing 4.2 isan example of a program that tests and modifies the instance variablesin apoint 
object. Point ispart of the java. awt package and refersto a coordinate point with an x and ay 
value. 


Type Listing 4.2. The TestPoint Class. 


1: import java.awt.Point; 

2: 

3: class TestPoint { 

4: 

5: public static void main (String args[]) { 

6: Point thePoint = new Point(10,10); 

7 

8 System.out.printin("X is " + thePoint.x); 
9 System.out.printin("Y is " + thePoint.y); 
10 

11 System.out.printin("Setting X to 5."); 

12 thePoint.x = 5; 

13 System.out.printin("Setting y to 15."); 
14: thePoint.y = 15; 

15 

16 System.out.printin("X is " + thePoint.x); 
17 System.out.printin("Y is " + thePoint.y); 
18 

19: } 

20: } 


X is 10 
Y is 10 
Output Setting X to 5. 
Setting y to 15. 
X is 5 
Y is 15 
And ™ Inthisexample, you first create an instanceof Point wherexand y areboth 10 (line6). Lines 
f yas 8 and 9 print out thoseindividual values, and you can see dot notation at work there. Lines 
11 through 14 change the values of those variables to 5 and 15, respectively. Finally, lines 


16 and 17 print out the values of x and y again to show how they've changed. 


Class Variables 


Class variables, as you learned before, are variables that are defined and stored in the classitself. 
Their values, therefore, apply to the class and to all its instances. 


With instance variables, each new instance of the class gets a new copy of the instance variables 
that class defines. Each instance can then change the values of those instance variables without 
affecting any other instances. W ith class variables, thereis only one copy of that variable. Every 
instance of the class has access to that variable, but there is only one value. C hanging the value 
of that variable changes it for all the instances of that class. 


You define class variables by including thestatic keyword beforethevariableitself. You'll learn 
more about this on D ay 6. For example, take the following partial class definition: 
class FamilyMember { 

static String surname = "Johnson"; 


String name; 
int age; 


} 


Instances of the class FamilyMember each have their own values for name and age. But the class 
variable surname hasonly onevaluefor all family members. C hangeésurnane, and all theinstances 
of FamilyMember are affected. 


To access class variables, you use the same dot notation as you do with instance variables. T o 
get or change the value of the class variable, you can use either the instance or the name of the 
class on the left side of the dot. Both the lines of output in this example print the same value): 
FamilyMember dad = new FamilyMember() 

System.out.printin("Family's surname is: " + dad.surname) ; 
System.out.printin("Family's surname is: " + FamilyMember.surname) ; 


Because you can use an instance to change the value of a class variable, it’s easy to become 
confused about class variables and where their values are coming from (remember, the value of 
a class variable affects all the instances). For this reason, it’s a good idea to usethe name of the 
class when you refer to a class variable— it makes your code easier to read and strange results 
easier to debug. 


Calling Methods 


Calling amethod in objectsis similar to referring to its instance variables: method calls also use 
dot notation. T he object whose method you're calling is on the left side of the dot; the name 
of the method and its arguments is on the right side of the dot: 


myObject.methodOne(arg1, arg2, arg3); 
N otethat all methodsmust haveparenthesesafter them, even if that method takesno arguments: 
myObject.methodNoArgs(); 


If the method you've called results in an object that itself has methods, you can nest methods 
as you would variables: 


myObject.getClass().getName() ; 
You can combine nested method calls and instance variable references as well: 


myObject.var.methodTwo(arg1, arg2); 
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System.out.printin(), the method you've been using all through the book this far, is a great 
example of nesting variables and methods. T he system Class (part of the java.1ang package) 
describes system-specific behavior. system. out isa class variable that containsan instanceof the 
class PrintStream that pointsto the standard output of thesystem. printstream instances have 
aprintin() method that prints a string to that output stream. 


Listing 4.3 shows an example of calling some methods defined in the string class. Strings 
include methods for string tests and modification, similar to what you would expect in astring 
library in other languages. 


Type Listing 4.3. Several Uses of string methods. 


1: class TestString { 

2: 

3 public static void main (String args[]) { 

4: String str = "Now is the winter of our discontent"; 
5: 

6: System.out.printin("The string is: " + str); 

7 System.out.printin("Length of this string: " 

8: + str.length()); 

9: System.out.printin("The character at position 5: " 
10: + str.charAt(5)); 
11: System.out.printin("The substring from 11 to 18: " 
12: + str.substring(11, 18)); 
13: System.out.printin("The index of the character d: " 
14: + str.indexOf('d')); 
15: System.out.print("The index of the beginning of the "); 
16: System.out.printin("substring \"winter\":" 
17: + str.indexOf ("winter") ); 
18: System.out.printin("The string in upper case: " 
19: + str.toUpperCase()); 
20: } 
21: } 


Length of this string: 35 

The character at position 5: s 

The substring from positions 11 to 18: winter 

The index of the character d: 25 

The index of the beginning of the substring "winter": 11 

The string in upper case: NOW IS THE WINTER OF OUR DISCONTENT 


0 | ut The string is: Now is the winter of our discontent 


A Fl ™ Inline4, you create a new instance of string by using a string literal (it’s easier that way 
N VS than using new and then putting the characters in individually). The remainder of the 
program simply calls different string methods to do different operations on that string: 


(| Line 6 prints the value of the string we created in line 4: "Now is the winter of our 
discontent". 
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Line 7 calls the 1ength() method in the new string object. This string has 35 charac- 
ters. 

Line 9 calls the charat() method, which returns the character at the given position in 
the string. N ote that string positions start at 0, so the character at position 5 is s. 


Line 11 calls the substring) method, which takes two integers indicating a range and 
returns the substring at those starting and ending points. The substring() method 
can also be called with only one argument, which returns the substring from that 
position to the end of the string. 


Line 13 calls the indexot() method, which returns the position of the first instance of 
the given character (here, 'a'). 

Line 15 shows a different use of the indexot() method, which takes a string argument 
and returns the index of the beginning of that string. 

Finally, line 18 uses the touppercase() method to return a copy of thestring in all 
uppercase. 


Class Methods 


Class methods, like class variables, apply to the class as a whole and not to its instances. C lass 
methods are commonly used for general utility methods that may not operate directly on an 
instance of that class, but fit with that class conceptually. For example, thestring class contains 
a class method called vaiueor(), which can take one of many different types of arguments 
(integers, booleans, other objects, and so on). The valueot() method then returns a new 
instanceof string containingthestring valueof theargument it wasgiven. T hismethod doesn’t 
operatedirectly on an existing instanceof string, but gettingastring from another object or data 
type is definitely a string-like operation, and it makes sense to define it in the string class. 


Class methods can also be useful for gathering general methodstogether in oneplace(theclass). 
For example, the math class, defined in the java.1ang package, contains a large set of 
mathematical operations as class methods— thereareno instances of the classmath, but you can 
sill use its methods with numeric or boolean arguments. 


T ocall aclassmethod, usedot notation asyou do with instancemethods. Aswith class variables, 
you can use either an instance of the class or the class itself on the left site of the dot. H owever, 
for the same reasons noted in the discussion on class variables, using the name of the class for 
class variablesmakesyour codeeasier to read. T helast two linesin thisexampleproducethesame 
result: 

String s, s2; 

s = "foo"; 

s.valueOf (5); 

String.valueOf (5) ; 
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References to Objects 


Asyou work with objects, oneimportant thing going on behind thescenesistheuseof references 
to those objects. W hen you assign objects to variables, or pass objects as arguments to methods, 
you are passing references to those objects, not the objectsthemselves or copies of those objects. 


An example should make this clearer. Examine the following snippet of code: 
import java.awt.Point; 
class ReferencesTest { 
public static void main (String args[]) { 
Point pt1, pt2; 


pt1 = new Point(100, 100); 
pt2 = pti; 


pti.x = 200; 
pti.y = 200; 
System.out.printin("Point1: " + pt1.x + ", " + pttl.y); 
System.out.printin("Point2: "+ pt2.x + ", " + pt2.y); 


} 
} 


In this program, you declare two variables of type Point, and assign anew Point object to pti. 
Then you assign the value of pt1 to pt2. 


N ow, here's the challenge. After changing pt1’s x and y instance variables, what will pt2 look 
like? 


H ere’s the output of that program: 
Point1: 200, 200 
Output Bohne 200, 200 
A | | — Asyou can see, pt2 wasalso changed. W hen you assign thevalueof pt1 to pt2, you actually 
fa V9 create a reference from p2 to the same object to which pt refers. Change the object that 


pt2refersto, and you also changethe object that pt1 pointsto, because both arereferences 
to the same object. 


Figure 4.1. ptt Point object 
References. oN x: 200 
pt2 >! y:200 


T he fact that | ava uses references becomes particularly important when you pass arguments to 
methods. You'll learn more about this later on today, but keep these references in mind. 
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Technical Note: T here areno explicit pointers or pointer arithmetic in J ava— just 
references. H owever, because of J ava references, you have most of the capabilities 
that you have with pointers without the confusion and lurking bugs that explicit 
pointers can create. 


Casting and Converting Objects and 
Primitive Types 


Sometimesin your] avaprogramsyou may haveavaluestored somewherethat isthewrongtype. 
M aybe it’s an instance of the wrong class, or perhapsit’s afioat and you want it to bean int, 
orit’san integer and you want it to be astring. T o convert the value of onetypeto another, you 
use a mechanism called casting. 


NEWe Casingisamechanism of converting the value of an object or primitivetype into another 
TERM type. Theresult of acast isanew object or value; casting doesnot affect the original object 
or value. 


Although theconcept of castingisasimpleone, therulesfor what typesin J avacan beconverted 
to what other types are complicated by the fact that J ava has both primitive types (int, float, 
boolean), and object types(string, Point, Window, and so on), Becauseof thesethreetypes, there 
are three forms of casts and conversions to talk about in this section: 


Casting between primitive types: int to float tO boolean 
[|] Casting between object types: an instance of aclass to an instance of another class 


Converting primitive types to objects and then extracting primitive values back out of 
those objects 


Casting Primitive Types 


Casting between primitive types enables you to “convert” the value of one type to another 
primitive type— for example, to assign a number of one type to a variable of another type 
Casting between primitivetypesmost commonly occurs with thenumeric types; boolean values 
cannot be cast to any other primitive type. You can, however, cast 1 or @ to boolean values. 


O ften, if the type you are casting to is “larger” than the typeof the value you’re converting, you 
may not have to use an explicit cast. You can often automatically treat a byte or a character as 
an int, for example, or an int aSa long, an int aSafloat, or anything asa double automatically. 
In this case, because the larger type provides more precision than the smaller, no loss of 
information occurs when the value is cast. 
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To convert alarge value to smaller type, you must use an explicit cast, because converting that 
value may result in aloss of precision. Explicit casts look like this: 


(typename) value 


In this form, typename is the name of the type you're converting to (for example short, int, 
float, boolean), and value is an expression that results in the value you want to convert. T his 
expression divides the values of x by the value of y and casts the result to an int: 


(int) (x / y)3 


N ote that because the precedence of casting is higher than that of arithmetic, you have to use 
parentheses so that the result of the division is what gets cast to an int. 


Casting Objects 


Instances of classes can also be cast to instances of other classes, with one restriction: the class 
of the object you’re casting and the class you're casting it to must berelated by inheritance that 
is, you can cast an object only to an instanceof its class’s sub- or superclass— not to any random 
Class. 


Analogousto converting aprimitive valueto alarger type, some objects may not need to be cast 
explicitly. In particular, because instances’ subclasses usually contain all the information that 
instances’ superclasses do, you can usean instanceof asubclass anywhereasuperclassis expected. 
Suppose you have a method that takes two arguments: one of type object, and one of type 
Number. YOu don’t haveto passinstances of thoseparticular classesto that method. Fortheobject 
argument, you can pass any subclass of object (any object, in other words), and for the number 
argument you can passin any instance of any subclass of Number (Integer, Boolean, Float, and 
SO On). 


Casting an object to an instance of one of that object’s superclasses loses the information the 
original subclass provided and requires a specific cast. T o cast an object to another class, you use 
the same casting operation that you used for base types: 


(classname) object 


In this case, classname is the name of the class you want to cast the object to, and object isa 
reference to the object you’re casting. N ote that casting creates a new instance of the new class 
with all the information that the old object contained; the old object still continues to exist as 
it did before. 


H ere'sa (fictitious) exampleof acast of an instance of theclassareenApple to an instanceof the 
class Apple (where GreenApple is theoretically a subclass of Appie): 


GreenApple a; 
Apple a2; 


a = new GreenApple(); 
a2 = (Apple) a; 


In addition to casting objects to classes, you can also cast objects to interfaces— but only if that 
object's class or one of its superclasses actually implements that interface. C asting an object to 
an interfacethen enables you to call oneof that interface’smethodseven if that object’sclass does 
not directly implement that interface. You'll learn more about interfaces in W eek 3. 


Converting Primitive Types 
to Objects and Vice Versa 


N ow you Know how to cast aprimitivetypeto another primitivetype and how to cast between 
Classes. H ow can you cast one to the other? 


You can’t! Primitive types and objects are very different things in Java and you can’t 
automatically cast or convert between thetwo. H owever, thejava.1ang packageincludes several 
special classes that correspond to each primitive data type Integer for intS, Float for floats, 
Boolean fOr booleans, and So on. 


U sing class methods defined in these classes, you can create an object-equivalent for all the 
primitivetypesusing new. T hefollowinglineof codecreatesan instanceof theinteger classwith 
the value 35: 


Integer intObject = new Integer (35) ; 


Once you have actual objects, you can treat those values as objects. Then, when you want the 
primitive values back again, there are methods for that as well— for example, the intvaiue() 
method extracts an int primitive value from an Integer object: 


int theInt = intObject.intValue(); // returns 35 


See the Java API documentation for these special classes for specifics on the methods for 
converting primitives to and from objects. 


Odds and Ends 


This section is a catchall for other information about working with objects, in particular: 


Comparing objects 

Copying objects 

| Finding out the class of any given object 

T esting to see whether an object is an instance of a given class 
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Comparing Objects 


Yesterday, you learned about operators for comparing values: equals, not equals, less than, and 
so on. M ost of theseoperatorswork only on primitivetypes, not on objects. If you try to useother 
values as operands, the] ava compiler produces errors. 


T heexception to thisruleiswith theoperatorsfor equality: == (equal) and != (not equal). T hese 
operators, when used with objects, tests whether the two operands refer to exactly the same 
object. 


What should you do if you want to be able to compare instances of your class and have 
meaningful results? You haveto implement special methods in your class, and you have to call 
those methods using those method names. 


Technical N ote: | ava does not have the concept of operator overloading— that is, 
the capability of defining the behavior of the built-in operators by defining meth- 
odsin your own classes. T he built-in operators renain defined only for numbers. 


A good example of thisis the string Class. It is possible to have two strings, two independent 
objects in memory with the same values— that is, the same characters in the same order. 
According to the == operator, however, those two string objects will not be equal, because, 
although their contents are the same, they are not the same object. 


The string class, therefore, defines a method called equais() that tests each character in the 
string and returns true if the two strings have the same values. Listing 4.4 illustrates this. 


Type Listing 4.4. A Test of String E quality. 


1: class EqualsTest { 

2: 

3 public static void main (String args[]) { 

4: String stri, str2; 

5: str1 = "she sells sea shells by the sea shore."; 

6: str2 = str1; 

7 

8: System.out.printin("String1: " + str1); 

9: System.out.printin("String2: " + str2); 

10: System.out.printin("Same object? " + (str1 == str2)); 
11: 

12: str2 = new String(str1); 

13: 

14: System.out.printin("String1: " + str1); 

15: System.out.printin("String2: " + str2); 

16: System.out.printin("Same object? " + (str1 == str2)); 
17: System.out.printin("Same value? " + str1.equals(str2)); 
18: } 

19: } 


String2: she sells sea shells by the sea shore. 
Same object? true 

String1: she sells sea shells by the sea shore. 
String2: she sells sea shells by the sea shore. 
Same object? false 

Same value? true 


A | r Thefirst part of this program (lines 4 through 6) declares two variables, stri and stra, 
falas assigns the literal she sells sea shells by the sea shore. tO stri1, and then assigns that 
value to str2. As you know from object references, now stri and str2 point to thesame 

object, and the test at line 10 proves that. 


Output String1: she sells sea shells by the sea shore. 


In the second part, you create a new string object with the value of str1. Now you have two 
different string objects with thesame value. T esting them to seewhether they’rethesame object 
by using the == operator (line 16) returns the expected answer, as does testing them using the 
equals method (line 17) to compare their values. 


Technical Note: W hy can’t you just use another literal when you change str2, 
rather than using new? String literals are optimized in J ava— if you create a string 
using aliteral, and then use another literal with the same characters, J ava knows 
enough merely to give you the first string object back. Both strings are the same 
objects— to create two separate objects you have to go out of your way. 


Copying Objects 
Recall from the section on object references that assigning variables and passing objects as 
arguments to methods affect only the object’s reference and doesn’t create copies of those 
objects. H ow do you create copies of objects? T here are two ways: the copy() method and the 
clone() method. 


T hecopy() method (defined in object, and so availableto all objects), takesasingleargument— 

another instanceof thesameclass— and copiesthe values of all theargument’sinstance variables 
into the instance variables of the current object (the onein which you're calling the method). 
N ote that if those instance variables in turn hold references to objects, only the references are 
copied, not the objects. 

Point pt1, pt2, pt3; 


pt1 = new Point(0,0); 
pt2 = new Point(100,100) ; 


pt2.copy(pt1); // pt1's values are copied into pt2; both now are (0,0). 
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The@cione() method issimilar to copy), except that clone() takesno arguments. T heclone() 
method creates a new instance of the same class as the source object and then copies the values 
of the instance variables (either primitive types or references to other objects). clone() returns 
an instance of the class object; to use it as an instance of the original class you have to cast it. 
H ere’s an example that clones the Point object in pt2 and stores the result in pts: 


pt3 = (Point) pt2.clone(); 


D etermining the Class of an Object 


W ant to find out the class of an object? H ere’s the way to do it for an object assigned to the 
variable obj: 


String name = obj.getClass().getName(); 


W hat doesthisdo?T hegetciass() method isdefined in theobject class, and assuch isavailable 
for all objects. The result of that method is aciass object (where class is itself a class), which 
has a method called getName(). getName) returns a string representing the name of the class. 


Another test that might be useful to you is the instanceof operator. instanceof has two 
operands: an object on theleft, and thenameof aclasson theright. Theexpression returnstrue 
Or false based on whether the object is an instance of the named class or any of that class’s 
superclasses: 

"foo" instanceof String // true 

Point pt = new Point(10,10); 

pt instanceof String // false 

The instanceof Operator can also be used for interfaces; if an object implements an interface, 
the instanceof operator with an interface name on the right side returns true. You'll learn all 
about interfaces in W eek 3. 


The J ava Class Libraries 


To finish up today, let’s look at the some of the J ava class libraries. Actually, you’ve had some 
experience with them already, so they shouldn’t seem that strange. 


The Java class libraries provide the set of classes that are guaranteed to be available in any 
commercial J ava environment (for example, in H ot] ava or in N etscape 2.0). T hose classes are 
in the java package and include all the classes you've seen so far in this book, plus a whole lot 
more classes you'll learn about later on in this book (and more you may not learn about at all). 


The Java D eveloper’s Kit comes with documentation for all the J ava class libraries, which 
includes descriptions of each class’sinstance variables, methods, constructors, interfaces, and so 
on. A shorter summary of the avaAPI isin Appendix B aswell. Exploring the} avaclasslibraries 
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and their methods and instance variables is a great way to figure out what J ava can and cannot 
do, as well as a starting point for your own development. 


H ere are the class packages that are part of the J ava class libraries: 


java. lang: Classes that apply to the language itself, which includes the object class, 
the string class, and the system Class. It also contains the special classes for the 
primitive types (Integer, Character, Float, and SO on). 

java.util: Utility classes, such as pate, as well as simple collection classes, such as 
Vector and Hashtable. 

java.io: Input and output classes for writing to and reading from streams (such as 
standard input and output) and for handling files. 

java.net: Classes for networking support, including socket and uat (a class to 
represent references to documents on the W orld Wide W eb). 

java.awt: (the Abstract Window T oolkit): Classes to implement a graphical user 
interface, including classes for window, Menu, Button, Font, CheckBox, and so on. This 
package also includes classes for processing images (the java. awt. Image package). 
java.applet: Classes to implement J ava applets, including the Appiet class itself, as 
well as the Audioci1ip Class. 


In addition to the J ava classes, your devedopment environment may also include additional 
classes that provideother utilities or functionality. Although theseclasses may beuseful, because 
they are not part of the standard J ava library, they won't be available to other people trying to 
run your J ava program. T hisis particularly important for applets, because applets are expected 
to be able to run on any platform, using any J ava-aware browser. O nly classes inside the java 
package are guaranteed to be available on all browsers and J ava environments. 


Summary 


Objects, objects everywhere. T oday, you learned all about how to deal with objects: how to 
create them, how to find out and change the values of their variables, and how to call their 
methods. You also learned how to copy and comparethem, and how to convert them into other 
objects. Finally, you learned a bit about the] ava class libraries— which give you a whole slew of 
Classes to play with in your own programs. 


You now have the fundamentals of how to deal with most simple things in the] ava language. 
All you have left are arrays, conditionals, and loops, which you'll learn about tomorrow. T hen 
you'll learn how to define and useclassesin | avaapplicationson D ay 6, and launch directly into 
applets next week. W ith just about everything you doin your] avaprograms, you'll alwayscome 
back to objects. 
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Q 


A 


Q 


I’m confused about the differences between objects and the primitive data types, 
such as int and boolean. 


The primitive types in the language (byte, short, int, long, float, double, and char) 
represent the smallest things in the language. T hey are not objects, although in many 
ways they can be handled like objects— they can be assigned to variables and passed in 
and out of methods. M ost of the operations that work exclusively on objects, however, 
will not. 


O bjects usually represent instances of classes and as such, are much more complex 
data types than simple numbers and characters, often containing numbers and 
characters as instance or class variables. 


In the section on calling methods, you had examples of calling a method with a 
different number of arguments each time— and it gave a different kind of result. 
H ow is that possible? 


T hat’s called method overloading. O verloading enables the same function name to have 
different behavior based on the arguments it’s called with— and the number and type 
of arguments can vary. When you define methods in your own classes, you define 
separate method signatures with different sets or arguments and different definitions. 
W hen that method is called, J ava figures out which definition to execute based on the 
number and type of arguments with which you called it. 


You'll learn all about this on D ay 6. 


No operator overloading in Java? Why not?! thought J ava was based on C ++, 
and C ++ has operator overloading. 


A Java was indeed based on C 4, but it was also designed to be simple, so many of 


C-H’s features have been removed. The argument against operator overloading is that 
because the operator can be defined to mean anything, it makes it very difficult to 
figure out what any given operator is doing at any onetime. T his can result in entirely 
unreadable code. Given the potential for abuse, the designers of J ava felt it was one of 
the C-++ features that was best left out. 
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Although you could write] ava programsusing what you'velearned so far, thoseprogramswould 
bepretty dull. M uch of the good stuff in J avaor in any programming language results when you 
have arrays to store values in and control-flow constructs (loops and conditionals) to execute 
different bits of a program based on tests. Today, you'll find out about the following: 


Arrays, one of the most useful objects in Java, which enable you to collect objects into 
an easy-to-manage list 

Block statements, for grouping together related statements 

if and switch, for conditional tests 


for and while loops, for iteration or repeating a statement or statements multiple 
times 


Arrays 


Arraysin J avaare different than they arein other languages. Arraysin J ava areactual objectsthat 
can be passed around and treated just like other objects. 


NEWe Arraysareaway to storealist of items. Each element of the array holds an individual item, 
TERM and you can place items into and renove items from those slots as you need to. 


Arrays can contain any type of value (base types or objects), but you can’t store different types 
in asingle array. You can havean array of integers, or an array of strings, or an array of arrays, 
but you can’t have an array that contains, for example, both strings and integers. 


To create an array in Java, you use three steps: 


1. Declare a variable to hold the array. 
2. Create a new array object and assign it to the array variable. 
3. Store things in that array. 


Declaring Array Variables 


T hefirst step to creating an array is creating a variable that will hold thearray, just as you would 
any other variable. Array variables indicate the type of object the array will hold (just as they do 
for any variable) and the name of thearray, followed by empty brackets ({ 1). T he following are 
all typical array variable declarations: 


String difficultWords[]; 
Point hits[]; 


int temps[]; 


An alternate method of defining an array variableis to put the brackets after the type instead of 
after the variable. T hey are equivalent, but this latter form is often much morereadable. So, for 
example, these three declarations could be written like this: 


String[] difficultWords; 
Point[] hits; 


int[] temps; 


Creating Array Objects 


T hesecond step is to create an array object and assign it to that variable. There are two ways to 
do this: 


U sing new 
Directly initializing the contents of that array 


The first way is to use the new operator to create a new instance of an array: 
String[] names = new String[10]; 


T hat linecreatesanew array of stringswith ten dots or eements. W hen you createthenew array 
object using new, you must indicate how many elements that array will hold. 


Array objects can contain primitive types such as integers or booleans, just as they can contain 
objects: 


int[] temps = new int[99]; 


W hen you create an array object using new, all itselements are initialized for you (a for numeric 
arrays, false for boolean, '\o' for character arrays, and nu11 for everything else). You can also 
create and initializean array at thesametime. Instead of using newto create thenew array object, 
enclose the elements of the array inside braces, separated by commas: 
String[] chiles = { "jalapeno", "anaheim", "serrano," 

"habanero," "thai" }; 
Each of the dements inside the braces must be of the same type and must be the same type as 
the variable that holds that array. An array the size of the number of elenents you've included 
will be automatically created for you. This example creates an array of string objects named 
chiles that contains five dements. 


Accessing Array Elements 


O nceyou havean array with initial values, you can test and changethevaluesin each slot of that 
array. To get at a value stored within an array, use the array subscript expression: 


myArray [subscript]; 81 
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T hemyArray part of this expression isa variable holding an array object, although it can also be 
an expression that resultsin an array). T h@subscript istheslot within thearray to access, which 
can also be an expression. Array subscripts start with a, as they do in C and CH: So, an array 
with ten elements has array values from subscript @ to 9. 


N otethat all array subscripts are checked to makesurethat they areinsidethe boundaries of the 
array (greater than 0 but lessthan the array’s length) either when your J avaprogram iscompiled 
or when it isrun. It isimpossible in J avato access or assign a value to an array element outside 
of the boundaries of the array. N ote the following two statenents, for example: 

String arr[] = new String[10]; 

arr[10] = "eggplant"; 

A program with that last statement in it produces a compiler error at that line when you try to 
compile it. The array stored in arr has only ten elements numbered from a, the dement at 
subscript 10 doesn’t exist, and the] ava compiler will check for that. 


If thearray subscript iscalculated at run-time(for example, aspart of aloop) and endsup outside 
theboundariesof thearray, the] avainterpreter also producesan error (actually, to betechnically 
correct, it throws an exception). You’ll learn more about exceptions later on next week and on 
Day 18. 


H ow can you keep from overrunning the end of an array accidentally in your own programs? 
You can test for the length of the array in your programs using the 1ength instance variable— 
it’s available for all array objects, regardless of type: 


int len = arr.length // returns 10 


Changing Array Elements 


To assign a valueto a particular array slot, merely put an assignment statement after the array 
access expression: 

myarray[1] = 15; 

sentence[@] = "The"; 

sentence[10] = sentence[O]; 

An important thing to note is that an array of objects in J avais an array of references to those 
objects (similar in some ways to an array of pointersin C or C-+4). When you assign a value to 
aslot in an array, you’re creating a reference to that object, just as you do for a plain variable. 
W hen you move values around insidearrays (asin that last line), you just reassign the reference; 
you don’t copy thevaluefrom oneslot to another. Arraysof primitivetypessuch asintSor floats 
do copy the values from one slot to another. 


Arrays of references to objects, as opposed to the objects themselves, are particularly useful 
because it means you can have multiple references to the same objects both inside and outside 
arrays— for example, you can assign an object contained in an array to avariableand refer to that 
same object by using either the variable or the array position. 


Multidimensional Arrays 


Java does not support multidimensional arrays. H owever, you can declare and create an array 
of arrays (and those arrays can contain arrays, and so on, for however many dimensions you 
need), and access them as you would C-style multidimensional arrays: 


int coords[][] new int[12][12]; 
coords[@][@] = 1; 


coords[0][1] 


B lock Statements 


A block statement isa group of other statenents surrounded by braces ({}). You can usea block 
anywhere a single statement would go, and the new block creates a new local scope for the 
statements insideit. T his meansthat you can declare and uselocal variables insidea block, and 
thosevariables will ceaseto exist after the block isfinished executing. F or example, here’sablock 
insidea method definition that declares anew variable y. You cannot usey outsidethe block in 
which it’s declared: 


void testblock() { 
int x = 10; 
{ // start of block 
int y = 50; 
System.out.printin("inside the block:"); 
System.out.printin("x:" + x); 
System.out.printin("y:" + y); 
} // end of block 
} 


Blocksarenot usually used in thisway— alonein amethod definition. You’vemostly seen blocks 
up to this point surrounding class and method definitions, but another very common use of 


block statements isin thecontrol flow constructs you'll learn about in the remainder of today’s 
lesson. 


if Conditionals 


Their conditional, which enables you to execute different bits of code based on a simpletest 
in Java, is nearly identical to it statements in C. it conditionals contain the keyword if, 
followed by a boolean test, followed by a statement (often a block statement) to execute if the 
test is true: 


if (x < y) 
System.out.printin("x is smaller than y"); 


An optional e1se keyword provides the statement to execute if the test is false: 


if (x < y) 
System.out.printin("x is smaller than y"); 
else System.out.printin("y is bigger."); 
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Technical N ote: T he difference between if conditionalsin Javaand C or C++is 
that the test must return a boolean value (true or false). Unlikein C, the test 
cannot return an integer. 


if (engineState == true ) 
System.out.printlin("Engine is already on."); 
else { 


System.out.println("Now starting Engine") ; 
if (gasLevel >= 1) 
engineState = true; 
else System.out.printin("Low on gas! Can't start engine."); 


T his example uses the test (enginestate == false). For boolean tests of this type, acommon 
shortcut is merely to includethefirst part of theexpression, rather than explicitly testing itsvalue 
against true or false: 

if (engineState) 


System.out.printlin("Engine is on."); 
else System.out.printin("Engine is off"); 


T he Conditional Operator 


An alternative to using the it and else keywords in a conditional statement is to use the 
conditional operator, sometimes called the ternary operator. 


NEWe- A conditional operator is a ternary operator because it has three terms. 
TERM 


The conditional operator is an expression, meaning that it returns a value (unlike the more 
general if, which can result in any statement or block being executed). T heconditional operator 
ismost useful for very short or simple conditionals, and looks like this: 


test ? trueresult : falseresult 


The test isan expression that returns true Or false, just likethe test in their statement. If the 
test is true, the conditional operator returns the value of trueresu1t; if it’s false, it returns the 
valueof falseresult. For example, thefollowing conditional teststhe values of x and y, returns 
the smaller of the two, and assigns that value to the variable smaller: 


int smaller =x <y?xi:y; 


The conditional operator has a very low precedence; that is, it’s usually evaluated only after all 
its subexpressions are evaluated. The only operators lower in precedence are the assignment 
operators. See the precedence chart in D ay 3’s lesson for a refresher on precedence of all the 
operators. 
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switch Conditionals 


A common practicein programming in any language isto test a variable against some value, and 
if it doesn’t match that value, to test it again against adifferent value, and if it doesn’t match that 
one to make yet another test, and so on. Using only it statements, this can become unwieldy, 
depending on how it’sformatted and how many different optionsyou haveto test. For example, 
you might end up with a set of it statements something like this or longer: 
if (oper == '+') 

addargs(arg1,arg2); 
else if (oper == '=') 

subargs(arg1,arg2) ; 


else if (oper == '*') 
multargs(arg1,arg2) ; 
else if (oper == '/') 


divargs(arg1,arg2) ; 


Thisform of it statement is called anested it, because each else statement in turn contains yet 
another if, and so on, until all possible tests have been made. 


A common shorthand mechanism for nested its that you can usein some cases allows you tests 
and actionstogether in asinglestatement. T hisistheswitch Or case Statement; in] avait’Sswitch 
and behaves as it doesin C: 


switch (test) { 
case valueOne: 
resultOne; 
break; 
case valueTwo: 
resultTwo; 
break; 
case valueThree: 
resultThree; 
break; 


default: defaultresult; 
} 
Intheswitch statement, thetest (a primitivetype of byte, char, short, Or int) iscompared with 
each of the case values in turn. If amatch is found, the statement, or statements after the test 
is executed. If no match is found, the defauit statement is executed. T he defauit is optional, 
so if there isn’t a match in any of the cases and defauit doesn’t exist, the switch statement 
completes without doing anything. 


N otethat the significant limitation of the switch in J avais that the tests and values can be only 
simple primitive types (and then only primitive types that are castable to int). You cannot use 
larger primitive types (1ong, float) or objects within a switch, nor can you test for any 
relationship other than equality. T hislimitstheusefulness of switch to all but thesimplest cases; 
nested ifs can work for any kind of test on any type 
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H ere's asimple example of a switch statement similar to the nested it shown earlier: 
switch (oper) { 
case '+': 
addargs(arg1,arg2); 
break; 
case '*': 
subargs(arg1,arg2); 
break; 
case '-': 
multargs(arg1,arg2) ; 
break; 
case '/': 
divargs(arg1,arg2) ; 
break; 


} 
N ote the break statement included in every line. Without the explicit break, once a match is 
made, thestatenents for that match and also all the statements further down in theswitch are 
executed until a break or theend of the switch isfound (and then execution continues after the 
end of the switch). In some cases, this may be exactly what you want to do, but in most cases, 
you'll want to makesureto includethebreak so that only thestatements you want to beexecuted 
are executed. 


One handy use of falling through occurs when you want multiple values to execute the same 
statements. In this instance, you can use multiple case lines with no result, and the switch will 
execute the first statements it finds. For example, in the following switch statement, the string 
"x is an even number." isprinted if x has values of 2,4, 6, or 8. All other values of x print the 
string "x is an odd number." 
switch (x) { 

case 2: 

case 4: 

case 6: 

case 8: 

System.out.printin("x is an even number."); 


break; 
default: System.out.printin("x is an odd number."); 


for Loops 


The for loop, asin C, repeats a statement or block of statements some number of times until 
a condition is matched. for loops are frequently used for simple iteration in which you repeat 
ablock of statenentsacertain number of times and then stop, but you can use for loopsfor just 
about any kind of loop. 


The for loop in Java looks roughly like this: 


for (initialization; test; increment) { 
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statements; 


} 
The start of the for loop has three parts: 


initialization iS an expression that initializes the start of the loop. If you havea loop 
index, this expression might declare and initialize it, for example, int i = 0. Variables 
that you declare in this part of the tor loop are local to the loop itself; they cease 
existing after the loop is finished executing. (T his is different from C or C-++) 


test IS the test that occurs after each pass of the loop. T he test must be a boolean 
expression or function that returns a boolean value, for example, i < 10. If the test is 
true, the loop executes. O nce the test is false, the loop stops executing. 

increment iS any expression or function call. Commonly, the increment is used to 
change the value of the loop index to bring the state of the loop closer to returning 
false and completing. 


Thestatement part of the tor loop is the statement that is executed each time the loop iterates. 
Just as with it, you can includeeither asingle statement here or a block; the previous example 
used a block because that is more common. H ere’s an example of a for loop that initializes all 
the values of a string array to null strings: 


String strArray[] = new String[10]; 
int i; // loop index 


for (i = 0; i < strArray.length; i++) 

strArray[i] = ""; 
Any of the parts of the for loop can be empty statements, that is, you can simply include a 
semicolon with no expression or statement, and that part of the for loop will be ignored. N ote 
that if you do useanull statement in your for loop, you may haveto initializeor increment any 
loop variables or loop indices yourself elsewhere in the program. 


You can also have an empty statement for the body of your for loop, if everything you want to 
doisin thefirst lineof that loop. For example, here’sonethat findsthefirst primenumber higher 
than 4000: 


for (i = 4001; notPrime(i); i += 2) 
N otethat acommon mistakein C that also occursin J avaisaccidentally to put asemicolon after 
the first line of the for loop: 
for (i = 0; i < 10; itt); 

System.out.printin("Loop!"); 
Because thefirst semicolon endstheloop with an empty statement, theloop doesn’t actually do 
anything. The printin function will be printed only once, because it’s actually outside the for 
loop entirely. Be careful not to make this mistakein your own Java programs. 
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while and do Loops 


Finally, there are while and do lOOpS. while and do loops, like for loops, enable a block of J ava 
code to be executed repeatedly until a specific condition is met. Whether you usea for loop, a 
while, Of ado ismostly a matter of your programming style. 


while and do loops, like for, are exactly the same as those same constructions in C and C-+. 


while Loops 


The white loop is used to repeat a statement or block of statements as long as a particular 
condition is true. while loops look like this: 
while (condition) { 

bodyOfLoop; 
} 
T heconditionisaboolean expression. If it returnstrue, thewnile loop executes the statements 
iN bodyofLoop and then tests the condition again, repeating until the condition is false. I’ve 
shown thewhile loop herewith ablock statement, becauseit’s most commonly used, although 
you can use a single statement in place of the block. 


H ere’s an example of awhile loop that copies the dements of an array of integers (in array1) 
to an array of floatS(in array2), casting each element to afloat asit goes. T heonecatch isthat 
if any of theelementsin thefirst array iso, theloop will immediately exit at that point. To cover 
both the cases wherein all the elements have been copied and an element is 0, you can use a 
compound test with the as operator: 
while ((ch != '' ') && (ch != '\t') && (ch != '\n') && (ch != '\r')) { 

addChar(ch, theName) ; 

ch = instream.read(); 
} 
N otethat if the condition isinitially falsethefirst timeitistested (for example, if thefirst element 
in that first array isa), the body of the white loop will never be executed. If you need to execute 
the loop at least once, you can do one of two things: 


D uplicate the body of the loop outside the while loop. 
Use ado loop (described below). 


T he do loop is considered the better solution of the two. 
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The do loop is just like awhile loop, except that do executes a given statement or block until a 
condition is false. The main difference is that wniie loops test the condition before looping, 
making it possible that the body of the loop will never execute if the condition is false the first 
time it’s tested. do loopsrun the body of the loop at least once before testing the condition. do 
loops look like this: 


sa oneaee 
} while (condition) ; 
H ere, the bodyofLoop part isthe statenentsthat are executed with each iteration. | t’sshown here 
with a block statement because it’s most commonly used that way, but you can substitute the 
braces for a single statement as you can with the other control-flow constructs. The condition 
isaboolean test. If it returns true, theloop isrun again. If it returns faise, theloop exits. K eep 
in mind that with do loops, the body of the loop executes at least once. 


H ere’s a Simple example of a do loop that prints a message each time the loop iterates: 
int x = 1; 


System.out.println("Looping, round " + x); 
Xt+5 
} while (x <= 10); 


H ere’s the output of these statements: 


Looping, round 
Output Looping, round 
Looping, round 
Looping, round 
Looping, round 
Looping, round 
Looping, round 
Looping, round 
Looping, round 
Looping, round 


S+tOANDOAARWNDN = 


Ss 


Breaking Out of Loops 


Inall theloops (for, while, and do), theloop endswhen the condition you're testing for ismet. 
W hat happensif something odd occurswithin thebody of theloop and you want to exit theloop 
early? For that, you can use the break and continue keywords. 
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You've already seen break as part of the switch statement; it stops execution of the switch, and 
the program continues. The break keyword, when used with a loop, does the same thing— it 
immediately halts execution of the current loop. If you've nested loops within loops, execution 
picks up in the next outer loop; otherwise, the program merely continues executing the next 
statement after the loop. 


For example, suppose you have awhile loop that copies dements from one array into another. 
Each element in the array should be copied until the end of the array is reached or if an dement 
contains. You can test for that latter case inside the body of the wni1e and then use a break to 
exit the loop: 


while (count < array1.length) { 


if (arrayi[count] == 0) { 
break; 

t 

array2[count] = array1[count]; 

count++; 


} 

} 

continue issimilar to break except that instead of halting execution of theloop entirely, theloop 
starts over at the next iteration. For do and while loops, this means the execution of the clock 
starts over again; for for loops, theincrement expression is evaluated and then block is executed. 
continue is useful when you want to special-case elements within a loop. With the previous 
example of copying onearray to another, you can test for whether the current element ise and 
restart theloop if you find it so that theresulting array will never contain zero. N otethat because 
you're skipping eements in the first array, you now have to keep track of two different array 
counters: 


while (count < array1.length) { 


if (array1[count] == Q) 
continue; 
array2[count2++] = (float)array1[count++]; 


} 


Labeled Loops 


Both break and continue Can have an optional label that tells) ava where to break to. Without 
alabedl, break jumps outside the nearest loop (to an enclosing loop or to the next statement 
outsidetheloop), and continue restarts the enclosing loop. U sing labeled breakS and continueS 
enables you to break outside nested loops or to continue a loop outside the current loop. 


T ousealabeled loop, add thelabel beforetheinitial part of theloop, with acolon between them. 
Then, when you use break OF continue, add the name of the label after the keyword itself: 
out: 
for (int i = 0; i <10; i++) { 
while (x < 50) { 
if (i * x == 400) 
break out; 


} 


In this snippet of code, thelabel out labelsthe outer for loop. Then, insideboth the for and the 
while loop, if a particular condition is met inside both loops, a break causes the execution to 
creak out of both loops and restart back at the label (out). 


H ere’sanother example. thefollowing program containsanested for loop. Insidetheinnermost 
loop, if the sum values of the two counters is greater than four, both loops exit at once: 


foo: 
for (int i = 1; i <= 5; i++) 
for (int j = 1; j <= 3; j++) { 
System.out.println("i is "+ i+ ", j is " + j); 
if ((i + j) > 4) 
break foo; 


} 
System.out.printin("end of loops"); 
H ere’s the output from this program: 


AL |} iis1, j is 1 

Output iis 1, j is 2 

ms | iis 1, j is 3 
iis 2, j is 1 
iis 2, j is 2 
iis 2, j is 3 
end of loops 


A laa Asyou can see, theloop iterated until thesum of i and j was greater than 4, and then both 
és nalyss loops exited back to the outer block and the final message was printed. 


Summary 


T oday, you learned about three main topics that you'll most likely use quite often in your own 
Java programs: arrays, conditionals, and loops. 


You learned how to declare an array variable, create and assign an array object to that variable, 
and access and change elements within that array. 
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Conditionalsincludetheit and switch statements, with which you can branch to different parts 
of your program based on a boolean test. 
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Finally, you learned about the for, while, and do loops, each of which enable you to executea 
portion of your program repeatedly until a given condition is met. 


N ow that you've learned thesmall stuff, all that’s left is to go over the bigger issues of declaring 
Classes and creating methodswithin which instancesof thoseclasses can communicatewith each 
other by calling methods. G et to bed early tonight, because tomorrow is going to beawild ride. 


Q&A 


Q 


A 


p> Oo 


p> oO 


If arrays are objects, and you use new to create them, and they have an instance 
variable length, where is the array Class?! didn’t see it in the J ava class libraries. 


Arrays are implemented kind of weirdly in J ava. The Array Class is constructed 
automatically when your J ava program runs; Array provides the basic framework for 
arrays, including the 1ength variable. Additionally, each primitive type and object has 
an implicit subclass of Array that represents an array of that class or object. W hen you 
create a new array object, it may not have an actual class, but it behaves as if it does. 

D oes Java have gotos? 

T he ava language defines the keyword goto, but it isnot currently used for anything. 
In other words, no, J ava does not have gotos. 

| declared a variable inside a block statement for an it. When the it was done, 
the definition of that variable vanished. Where did it go? 

In technical terms, block statements inside braces form a new lexical scope. W hat this 
means is that if you declare a variable inside a block, it’s only visible and usable inside 
that block. O nce the block finishes executing, all the variables you declared go away. 
It’s a good idea to declare most of your variables in the outermost block in which 
they'll be needed— usually at the top of a block statement. T he exception might be 
very simple variables, such as index counters in for loops, where declaring them in the 
first line of the for loop is an easy shortcut. 

You'll learn more about variables and scope tomorrow. 

W hat can’t you use switch with strings? 

Strings are objects, and switch in Java works only for the primitive types that can be 
cast to integers (byte, char, short, and int). To compare strings, you have to use 
nested its, which enable more general expression tests, including string comparison. 


Q Itseems to me that a lot of for loops could be written as white loops, and vice 
versa. 

A True The for loop is actually a special case of white that enables you to iterate aloop 
a specific number of times. You could just as easily do this with awhile and then 
increment a counter inside the loop. Either works equally well. This is mostly just a 
question of programming style and personal choice. 
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In just about every lesson up to this point you've been creating Java applications— writing 
classes, creating instance variables and methods, and running those applications to perform 
simple tasks. Also up to this point, you've focused either on the very broad (general object- 
oriented theory) or the very minute (arithmetic and other expressions). T oday, you pull it all 
together and learn how and why to create classes by using the following basics: 


The parts of a class definition 
Declaring and using instance variables 
Defining and using methods 


Creating J ava applications, including the main() method and how to pass arguments 
to aJava program from a command line 


D efining Classes 


D efining classes is pretty easy; you've seen how to do it abunch of timesin previous lessons. T 0 
define a class, use the class keyword and the name of the class: 


class MyClassName { 

a 

If this class is a subclass of another class, use extends to indicate the superclass of this class: 
class myClassName extends mySuperClassName { 

- 

If this class implements a specific interface, use implements to refer to that interface 

class MyRunnableClassName implements Runnable { 

- 


Both extends and implements are optional. You'll learn about using and defining interfaces in 
W eek 3. 


Creating Instance and Class Variables 


A class definition with nothing in it is pretty dull; usually, when you create a class, you have 
something you want to add to make that class different from its superclasses. Inside each class 
definition are declarations and definitions for variables or methods or both— for the class and 
for each instance. In this section, you'll learn all about instance and class variables; the next 
section talks about methods. 
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D efining I nstance Variables 


On Day 3, you learned how to declare and initialize local variables— that is, variables inside 
method definitions. Instance variables, fortunately, aredeclared and defined in exactly the same 
way as local variables; the only difference is their location in the class definition. Instance 
variables are considered instance variables if they are declared outside a method definition. 
Customarily, however, most instance variables are defined just after the first line of the class 
definition. For example, Listing 6.1 showsasimple class definition for theclassBicycie, which 
inherits from the class PersonPoweredVehicle. This class definition contains four instance 
variables: 


bikeType: the kind of bicycle this bicycle is— for example, mountain Or Street 
chainGear, the number of gears in the front 
rearCogs, thenumber of minor gears on the rear axle 


currentGearFront and currentGearrear: the gears the bike is currently in, both front 
and rear 


1: class Bicycle extends PersonPoweredVehicle { 
2: String bikeType; 

3: int chainGear; 

4: int rearCogs; 

5: int currentGearFront; 

6 int currentGearRear; 

7 


Constants 


Constants are useful for setting global states in a method or object, or for giving meaningful 
names to object-wide values that will never change. In J ava, you can create constants only for 
instance or class variables, not for local variables. 


NEWe- A congant variable or consant is a variable whose value never changes (which may seem 
TERM strange given the meaning of the word “variable”). 


To declare a constant, use the fina keyword before the variable declaration and include an 
initial value for that variable: 
final float pi = 3.141592; 


final boolean debug = false; 
final int maxsize = 40000; 
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Technical Note: T he only way to define constants in Java is by using the final 
keyword. N either theC and C ++ constructs for #define nor const are available in 
Java. 


Constants can be useful for naming various states of an object and then testing for those states. 
For example, suppose you haveatest label that can bealigned left, right, or center. You can define 
those values as constant integers: 


final int LEFT = Q; 

final int RIGHT = 1; 

final int CENTER = 2; 

The variable alignment is then also declared as an int: 

int alignment; 

Then, later on in the body of a method definition, you can either set the alignment: 
this.alignment = CENTER; 

or test for a given alignment: 


switch (this.alignment) { 
case LEFT: // deal with left alignment 


break; 

case RIGHT: // deal with right alignment 
break; 

case CENTER: // deal with center alignment 


break; 


Class Variables 


As you learned in previous lessons, class variables are global to a class and to all that class's 
instances. You can think of classvariablesasbeing even moreglobal than instancevariables. C lass 
variables are good for communicating between different objects with the same class, or for 
keeping track of global states among a set of objects. 


To declarea class variable, use the static keyword in the class declaration: 


static int sum; 
static final int maxObjects = 10; 
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Creating Methods 


M ethods, asyou learned on D ay 2, definean object's behavior— what hanpenswhen that object 
iscreated and the various operations that object can perform during its lifetime. In this section, 
you'll get abasic introduction to method definition and how methods work; tomorrow, you'll 
go into more detail about advanced things you can do with methods. 


D efining Methods 


M ethod definitions have four basic parts: 


Thename of the method 

The type of object or base type this method returns 
A list of parameters 

The body of the method 


NEWe Themethod’ssgnatureisacombination of thename of the method, thetype of object or 
TERM basetype this method returns, and alist of parameters. 


Note: T 0 keep things simple today, I’ve left off two optional parts of the method 

definition: an access qualifier such aS public OF private, and the throws keyword, 
which indicates the exceptions a method can throw. You'll learn about these parts 
of amethod definition in W eek 3. 


In other languages, the name of the method (or function, subroutine, or procedure) is enough 
to distinguish it from other methods in the program. In J ava, you can have different methods 
that have the same name but a different return type or argument list. This is called method 
overloading, and you'll learn more about it tomorrow. 


H ere’s what a basic method definition looks like: 
returntype methodname (type? arg1, type2 arg2, type3 arg3..) { 


} 
Theéreturntype isthe primitive type or class of the of the value this method returns. It can be 
one of the primitive types, a class name, or void if the method does not return a value at all. 


N otethat if thismethod returnsan array object, the array brackets can go either after the return 
type or after the parameter list; because the former way is considerably easier to read, it is used 
in the examples today (and throughout this book): 


int[] makeRange (int lower, int upper) {...} 
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The method's parameter list is a set of variable declarations, separated by commas, inside 
parentheses. T hese parameters become local variables in the body of the method, whose values 
are the objects or values of primitives passed in when the method is called. 


Inside the body of the method you can have statements, expressions, method calls to other 
objects, conditionals, loops, and so on— everything you'velearned about in thepreviouslessons. 


If your method hasareal return type(thatis, it hasnot been declared to return void), somewhere 
inside the body of the method you need to return a value. U sethe return Keyword to do this. 
Listing 6.2 shows an example of aclass that defines a makeRange() method. makeRange( ) takes 
two integers— alower bound and an upper bound— and creates an array that contains all the 
integers between those two boundaries (inclusive). 


Type Listing 6.2. The RangeClass Class. 


1: class RangeClass { 

2 int[] makeRange (int lower, int upper) { 

3 int arr[] = new int[ (upper - lower) + 1 ]; 
4: 

5: for (int i = 0; i < arr.length; i++) { 
6: arr[i] = lowert++; 

7 } 

8: return arr; 

9: } 

10: 

11: public static void main (String arg[]) { 

12: int theArray[]; 

13: RangeClass theRange = new RangeClass(); 
14: 

15: theArray = theRange.makeRange(1,10); 

16: System.out. print (° ‘The array: [ "); 

17: for (int i = 0; i < theArray. length; it+) { 
18: System.out.print(theArray[i] + " "); 
19: } 

20: System.out.printin("]"); 

21: } 

22: 

23: } 


H ere’s the output of this program: 


Output The array: [123456789 10 ] 


A | Themain() method in this class tests the makeRange() method by creating a range where 
Na 95 thelower and upper boundaries of therangeare1 and 10, respectively (seeline6), and then 
uses a for loop to print the values of the new array. 


The this Keyword 


Sometimes, in the body of amethod definition, you may want to refer to the current object— 
for example, to refer to that object’s instance variables or to pass the current object as an 
argument to another method. To refer to the current object in these cases, you can usethethis 
keyword. this refers to the current object, and you can use it anywhere that object might 
appear— in dot notation to refer to the object’s instance variables, as an argument to amethod, 
as the return value for the current method, and so on. H ere’s an example 


t = this.x // the x instance variable for this object 
this.myMethod(this) // call the mymethod method, defined in 

// this class, and pass it the current 

// object 
return this; // return the current object 


In many cases, however, you may be able to omit the this keyword. You can refer to both 
instance variables and method calls defined in the current class simply by name; the this is 
implicit in those references. So, the first two examples could be written like this: 


t =x // the x instance variable for this object 
myMethod(this) // call the myMethod method, defined in this 
// class 


Note: O mitting the this keyword for instance variables depends on whether there 
are no variables of the same name declared in the local scope. See the next section 
for details. 


Keep in mind that because this is a reference to the current instance of a class, it makes sense 
to useit only insidethe body of an instance method definition. C lass methods, that is, methods 
declared with the static keyword, cannot use this. 


Variable Scope and Method Definitions 


W hen you refer to avariablewithin your method definitions, J avachecksfor adefinition of that 
variable first in the current scope (which may bea block), then in the outer scopes up to the 
current method definition. If that variableisnot alocal variable, J avathen checksfor adefinition 
of that variable as an instance variable in the current class, and then, finally, in each superclass 
in turn. 


Because of the way J ava checks for the scope of agiven variable, it is possible for you to create 
avariablein alower scope such that adefinition of that same variable “hides” the original value 
of that variable. T his can introduce subtle and confusing bugs into your code. 
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For example, note this small J ava program: 


class ScopeTest { 
int test = 10; 


void printTest () { 
int test = 20; 
System.out.printin("test = " + test); 
} 
} 
In this class, you have two variables with the same name and definition: the first, an instance 
variable, hasthenametest and isinitialized to the value 10. T hesecond is alocal variable with 
thesamename, but with the value 20. Becausethe local variable hides the instance variable, the 
printin() method will print that test iS 20. 


You can get around this particular instance by using this. test to refer to theinstance variable, 
and just test to refer to the local variable. 


A moreinsidious example of this occurs when you redefine a variable in a subclass that already 
occursin asuperclass. T hiscan create very insidious bugsin your code— for example, you may 
call methods that are intended to change the value of an instance variable, but that change the 
wrong one. Another bug might occur when you cast an object from one class to another— the 
value of your instance variable may mysteriously change (because it was getting that valuefrom 
the superclass instead of from your class). T he best way to avoid this behavior is to make sure 
that, when you define variables in a subclass, you're aware of the variablesin each of that class's 
superclasses and you don’t duplicate what is already there. 


Passing Arguments to Methods 


When you call a method with object parameters, the variables you pass into the body of the 
method are passed by reference, which means that whatever you do to those objects inside the 
method affects the original objects as well. T his includes arrays and all the objects that arrays 
contain; when you pass an array into a method and modify its contents, the original array is 
affected. (N ote that primitive types are passed by value.) 


H ere’s an example to demonstrate how this works. First, you have a simple class definition, 
which includes a single method called oneToZero() (see Listing 6.3). 


Type Listing 6.3. The PassByReference Class. 


1: class PassByReference { 

2 int OnetoZero (int arg[]) { 

3: int count = 0; 

4: 

5: for (int i = 0; i < arg.length; i++) { 
6 if (arg[i] == 1) { 
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7: count++; 

8: arg[i] = Q; 
9: } 

10: } 

V1: return count; 


The onetozero() method does two things: 


It counts the number of onesin the array and returns that value. 
If it finds a one, it substitutes a zero in its place in the array. 


Listing 6.4 showsthemain,) method for thepassByReference Class, which teststheonetoZzero() 
method: 


‘Type Listing 6.4. The main() method in PassByReference. 


1: public static void main (String arg[]) { 

2: int arr[] = {1, 3, 4, 5, 1, 1, 7 }; 

3 PassByReference test = new PassByReference() ; 

4 int numOnes; 

5: 

6: System.out.print("Values of the array: [ "); 

Ti for (int i = 0; i < arr.length; i++) { 

8 System.out.print(arr[i] + " ") 

9 } 

10 System.out.printin("]"); 

11 

12: numOnes = test.OnetoZero(arr) ; 

13: System.out.printin("Number of Ones = " + numOnes) ; 
14: System.out.print("New values of the array: [ "); 
15: for (int i = 0; i < arr.length; i++) { 

16: System.out.print(arr[i] + " ") 

17: 

18: System.out.printin("]"); 

19: } 


H ere is the output of this program: 
‘Alu. 4 Values of the array: [1345117 ] 
Output Number of Ones = 3 
New values of the array: [0345007 ] 
Analysis Let's go over the main() method line by line so that you can see what is going on. 
Lo | 


Lines2 through 4 set up theinitial variables for this example. T hefirst oneisan array of integers; 
the second oneisan instance of the class passByReference, which is stored in the variable test. 
Thethird is a simple integer to hold the number of ones in the array. 
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Lines 6 through 11 print out the initial values of the array; you can see the output of these lines 
in the first line of the output. 


Line12 iswherethereal work takesplace; thisiswhereyou call theonetozero() method, defined 
in the object test, and pass it the array stored in arr. Thismethod returns the number of ones 
in the array, which you'll then assign to the variable numones. 


Got it so far? Line 13 prints out the number of ones, that is, the value you got back from the 
OnetoZero() method. It returns three, as you would expect. 


T helast bunch of lines print out thearray values, B ecauseareferenceto thearray object is passed 
to the method, changing the array inside that method changes that original copy of the array. 
Printing out the valuesin lines 14 through 18 proves this— that last line of output shows that 
all the 1sin the array have been changed to as. 


Class Methods 


Just as you have class and instance variables, you also have class and instance methods, and the 
difference between thetwo types of methodsareanalogous. Classmethodsareglobal to theclass 
itself and availableto any other classes or objects. T herefore, class methodscan beused anywhere 
regardless of whether an instance of the class exists or not. 


For example, the J ava class libraries include a class called math. T he math class defines a whole 
set of math operations that can be used in any program with the various number types: 
float root = Math.sqrt(453.0) ; 

System.out.print("The larger of x and y is" + Math.max(x,y)); 

To define class methods, usethe static keyword in front of the method definition, just as you 
would createaclass variable F or example, that max class method might haveasignaturelikethis: 


static int max (int argi, int arg2) { ... } 


In asimilar example, J ava supplies “wrapper” classes for each of the base types— for example, 
Classes for Integer, Float, and Boolean. U sing class methods defined in those classes, you can 
convert to and from objects and base types. For example, the parsernt() class method in the 
Integer Class takes a string and a radix (base) and returns the value of that string as an integer: 


int count = Integer.parseInt("42", 10) // returns 42 


M ost methods that operate on a particular object, or that affect that object, should be defined 
as instance methods. M ethods that provide some general utility but do not directly affect an 
instance of that class are better declared as class methods. 


Creating J ava Applications 


N ow that you know how to create classes, objects, and classand instancevariablesand methods, 
all that’s left isto put it together into something that can actually run— in other words, to create 
a] ava application. 


Applications, to refresh your memory, are] ava programs that run on their own. Applications 
aredifferent from applets, which requireH ot] avaor aj ava-capablebrowser to view them. M uch 
of what you’vebeen using up to thispoint havebeen J ava applications; next week you'll diveinto 
how to create applets. (Applets require a bit more background in order to get them to interact 
with the browser and draw and update with the graphics system. You'll learn all of this next 
week.) 


A Java application consists of one of more classes and can be as large or as small as you want it 
to be. H ot] ava is an example of a] ava application. The only thing you need to make a Java 
application run is one class that serves as the “jumping-off” point for the rest of your Java 
program. If your program is small enough, it may need only the one class. 


T hejumping-off classfor your program needsonething: amain() method. When you run your 
compiled J ava class (using the J ava interpreter), the main() method is the first thing that gets 
called. N oneof thisshould bemuch of asurpriseto you at this point; you’ve been creating J ava 
applications with main() methods all along. 


The signature for the main() method always looks like this: 
public static void main (String arg[]) {...} 


H ere’s arun-down of the parts of the main() method: 


public means that this method is available to other classes and objects. T he main) 
method must be declared public. You'll learn more about public and private 
methods in W eek 3. 


static means that this is a class method. 
void means the main) method doesn’t return anything. 


main() takes one parameter: an array of strings. T his argument is used for command- 
line arguments, which you'll learn about in the next section. 


The body of the main() method contains any code you need to get your application started: 
initial variables or creating instances of any classes you may have declared. 


W hen J ava executes the main) method, keep in mind that main) isaclassmethod— the class 
that holdsit isnot automatically instantiated when your program runs. If you want to treat that 
Class as an object, you have to instantiate it in the main) method yourself (all the examples up 
to this point have done this). 
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J ava Applications and Command-Line 
Arguments 


Because J ava applications are stand-alone programs, it’s useful to be able to pass arguments or 
options to that program to determine how the program is going to run, or to enable a generic 
program to operate on many different kinds of input. Command-line arguments can be used 
for many different purposes— for example, to turn on debugging input, to indicate a filename 
to read or write from, or for any other information that you might want your J ava program to 
know. 


Passing Arguments to J ava Programs 


T 0 pass arguments to aJ avaprogram, you merely append them to the command linewhen you 
run your J ava program: 


java Myprogram argumentOne 2 three 


Onthiscommand line, you havethree arguments: argumentone, thenumber 2, and three. N ote 
that a space separates arguments, so this command line produces three arguments: 


java myprogram Java is cool 


To group arguments, surround then with double-quotes. T his command line produces one 
argument: 


java myprogram "Java is cool" 


T he double-quotes are stripped off before the argument gets to your J ava program. 


Handling Arguments in Your J ava Program 


H ow does] ava handle arguments? It stores them in an array of strings, which is passed to the 
main() method in your J ava program. Renember the signature for main(): 


public static void main (String arg[]) {...} 

H eve arg isthenameof thearray of stringsthat contains thelist of arguments. You can actually 
call it anything you want; argv iscommon (after the array of thesamenamefrom C and Unix 
shell scripting). 

Inside your main() method, you can then handle the arguments your program was given by 


iterating over the array of arguments and handling those arguments any way you want. For 
example, Listing 6.5 is a really simple class that prints out the arguments it gets, one per line 
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1: class EchoArgs { 

2 public static void main(String args[]) { 

3 for (int i = 0; i < args.length; i++) { 

4: System.out.printin("Argument "+ i+ ": " + args[i]); 
5: } 

6 

7 


: } 


The following is some sample input and output from this program: 


java EchoArgs 1 2 3 jump 

| |} Argument 0: 1 
Output Argument 1: 2 
: | Argument 2: 3 
Argument 3: j 


java EchoArgs "foo bar" zap twaddle 5 


lA....2 Argument @: foo bar 
Output Argument 1: zap 
bs Argument 2: twaddle 
Argument 3: 5 
N ote how the arguments are grouped in the listing; putting quotes around foo bar causes that 
argument to be treated as one unit inside the argument array. 


Technical Note: T he array of arguments in J avais not analogous to argv in C and 
Unix. In particular, argoj, the first element in the array of arguments, is the first 
command-line argument after the name of the class— not the name of the program 
as it would bein C. Be careful of this as you write your J ava programs. 


An important thing to note about the arguments you pass into a Java program is that those 
arguments will be stored in an array of strings. T his means that any arguments you pass to your 
Java program will be converted to strings so they can be stored in the argument array. T o treat 
them as non-strings, you’ll have to convert them to whatever type you want them to be. 


For example, suppose you have a very simple J ava program called sumAverage that takes any 
number of numeric arguments and returnsthesum and the average of those arguments. Listing 
6.6 shows a first pass at this program. 
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Type Listing 6.6. First try at the sumAverage class. 


1: class SumAverage { 

2 public static void main (String args[]) { 

3 int sum = Q; 

4: 

5: for (int i = 0; i < args.length; i++) { 

6: sum += args[i]; 

7 } 

8: 

9: System.out.printin("Sum is: " + sum); 
10: System.out.printin("Average is: " + 
11: (float)sum / (float)args.length) ; 
12: } 

13: } 


A | Atfirst glance, thisprogram seemsrather straightforward— ator loop iterates over thearray 
Na V9 of arguments, summing them, and then thesum and theaverageare printed out asthelast 
step. 


W hat happens when you try and compile this? You get the following error: 


SumAverage.java:9: Incompatible type for +=. Can't convert java.lang.String to int. 
sum += args[i]; 

You get this error because the argument array is an array of strings. Even though you passed 

integers into the program from the command line, those integers were converted to strings 

before they werestored in thearray. T o beableto sum thoseintegers, you haveto convert then 

back from strings to integers. T here’s a class method for the rnteger class, called parseint, that 

does just this. If you change line 7 to use that method, everything works just fine 


sum += Integer.parseInt(args[i]); 


N ow, compiling the program producesno errorsand runningit with variousarguments returns 
the expected results. For example, java SumAverage 1 2 3 returns the following output: 


Sum is: 
Outp ere is: 2 


Summary 


T oday, you put together everything you've comeacrossin thepreceding days of this week about 
how to create J ava classes and use them in J ava applications. T his included the following: 


_| Instance and class variables, which hold the attributes of the class and its instances. 
You learned how to declare them, how they are different from regular local variables, 
and how to declare constants. 
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Instance and class methods, which define a class's behavior. You learned how to define 
methods, including the parts of a method's signature, how to return values from a 
method, how arguments are passed in and out of methods, and the this keyword to 
refer to the current object 

Java applications— all about the main) method and how it works as well as how to 
pass arguments into a Java application from a command line. 
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| tried creating a constant variable inside a method, and | got a compiler error 
when | tried it. What was! doing wrong? 

You can create only constant (fina1) class or instance variables; local variables cannot 
be constant. 

static and final are not exactly the most descriptive words for creating class 
variables, class methods, and constants. W hy not use class and const? 


static comes from Java's C ++ heritage, C + uses the static keyword to retain 
memory for class variables and methods (and, in fact, they aren’t called class methods 
and variables in C +: static member functions and variables are more common 
terms). 


final, however, is new. final is used in amore general way for classes and methods to 
indicate that those things cannot be subclassed or overridden. U sing the final 
keyword for variables is consistent with that behavior. fina1 variables are not quite the 
same as constant variables in C +, which is why the const keyword is not used. 


In my class, | have an instance variable called name. | also have a local variable 
called name in a method, which, because of variable scope, gets hidden by the 
local variable. Is there any way to get hold of the instance variable’s value? 


T he easiest way is not to name your local variables the same names as your instance 
variables. If you feel you must, you can use this.name to refer to the instance variable 
and name to refer to the local variable. 

| want to pass command-line arguments to an applet. H ow do | do this? 

You're writing applets already? Been skipping ahead, have you? T he answer is that you 
useH TM L attributes to pass arguments to an applet, not the command line (you 
don't haveacommand line for applets). You'll learn how to do this next week. 


| wrote a program to take four arguments, but if | give it too few arguments, it 
crashes with a run-time error. 

T esting for the number and type of arguments your program expects is up to you in 
your J ava program; Java won’t do it for you. If your program requires four arguments, 
test that you have indeed been given four arguments, and return an error message if 
you haven't. 
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M ethods arearguably themost important part of any object-oriented language. W hereas classes 
and objects provide the framework, and class and instance variables provide a way of holding 
that class or object’s attributes and state, it is the methods that actually provide an object’s 
behavior and define how that object interacts with other objects in the system. 


Yesterday, you learned alittle about defining methods. With what you learned yesterday, you 
could create lots of Java programs, but you’d be missing some of the features of methods that 
make them really powerful, that make your objects and classes more efficient and easier to 
understand. T oday, you'll learn about these additional features, including the following: 


Overloading methods, sometimes called creating polymorphic methods— that is, 
creating methods with multiple signatures and definitions but with the same name 


Creating constructor methods— methods that enable you to initialize objects to set up 
an initial state in the system when an object is created 


O verriding methods— creating a different definition for a method that has been 
defined in a superclass 


Finalizer methods— a way for an object to clean up after itself before it is renoved 
from the systen 


Creating Methods with the Same 
Name, Different Arguments 


Yesterday, you learned how to create methods with a single name and a single signature. 
M ethods in Java can also be overloaded— that is, you can create methods that have the same 
name, but different signatures and different definitions. M ethod overloading enables instances 
of your class to havea simpler interface to other objects (no need for entirely different methods 
that do essentially thesame thing) and to behavedifferently based on theinput to that method. 


When you call amethod in an object, J ava matches up the method name and thenumber and 
type of arguments to choose which method definition to execute. 


T ocreatean overloaded method, all you need to do iscreate several different method definitions 
in your class, all with thesamename, but with different parameter lists (either in number or type 
of arguments) and with different bodies. Java can understand method overloading as long as 
each parameter list is unique for each method name. 


N otethat J ava differentiates overloaded methodswith thesamename, based on thenumber and 
typeof parametersto that method, not onitsreturn type. T hatis, if you try to createtwo methods 
with thesamename, same parameter list, but different return types, you'll get a compiler error. 
T hevariablenames you choosefor each parameter to themethod areirrelevant— all that matters 
isthe number and the type. 
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H ere’san example of creating an overloaded method. Listing 7.1 showsasimpleclass definition 
for a class called myrect, which defines a rectangular shape. T hemyrect class has four instance 
variables to define the upper left and lower right corners of the rectangle: x1, y1, x2, and y2. 


Note: Why did | call it myrRect? J ava’s awt package has a class called Rectangle that 
implements much of this same behavior. | called this class myrect to prevent 
confusion between the two classes. 


Type Listing 7.1. The myRect class. 


class MyRect { 
int x1 
int y1 
int x2 
int y2 


W hen anew instanceof themyrect classisinitially created, all itsinstancevariablesareinitialized 
to o. Let’s define a buildrRect() method that takes four integer arguments and “resizes” the 
rectangle to have the appropriate values for its corners, returning the resulting rectangle object 
(note that because the arguments have the same names as the instance variables, you have to 
make sure to use this to refer to them): 


MyRect buildRect(int x1, int y1, int x2, int y2) { 


this.x1 = x1; 
this.y1 = y1; 
this.x2 = x2; 
this.y2 = y2; 


return this; 
} 
W hat if you want to define arectangle’s dimensionsin a different way— for example, by using 
Point Objects rather than individual coordinates? You can overload buildrect() So that its 
parameter list takes two Point objects (note that you'll need to import the point class at thetop 
of your source file so J ava can find it): 
MyRect buildRect(Point topLeft, Point bottomRight) { 

x1 = topLeft.x; 

y1 topLeft.y; 

x2 = bottomRight.x; 


y2 = bottomRight.y; 
return this; 
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Perhaps you want to definethe rectangle using atop corner and awidth and height. J ust create 
adifferent definition for buildrect(): 


MyRect buildRect(Point topLeft, int w, int h) { 


x1 = topLeft.x; 
y1 = topLeft.y; 
x2 = (x1 + w); 
y2 = (y1 +h); 


return this; 


To finish up this example, let’s create a method to print out the rectangle’s coordinates, and a 
main() method to test it all (just to prove that this does indeed work). Listing 7.2 shows the 
completed class definition with all its methods. 


Type Listing 7.2. The complete myRect class. 


import java.awt.Point; 


class MyRect { 
int x1 = Q; 
int y1 = Q; 
int x2 = Q; 
int y2 = Q; 
MyRect buildRect(int x1, int y1, int x2, int y2) { 
this.x1 = x1; 
this.y1 = y1; 
this.x2 = x2; 
this.y2 = y2; 
return this; 
} 
MyRect buildRect(Point topLeft, Point bottomRight) { 
x1 = topLeft.x; 
y1 = topLeft.y; 
x2 = bottomRight.x; 
y2 = bottomRight.y; 
return this; 
} 
MyRect buildRect(Point topLeft, int w, int h) { 
x1 = topLeft.x; 
y1 = topLeft.y; 
x2 = (x1 + w); 
y2 = (yi +h); 
return this; 
} 
void printRect() { 
System.out.print("MyRect: <" + x1 + ", " + y1); 
System.out.printin(", "+ x2 + ", "+ y2 + ">"); 
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public static void main (String args[]) { 
MyRect rect = new MyRect(); 


System.out.printin("Calling buildRect with coordinates 25,25 50,50:"); 
rect.buildRect(25, 25, 50, 50); 

rect.printRect(); 

System.out.printlin("---------- *)5 


System.out.printlin("Calling buildRect w/points (10,10), (20,20):"); 
rect.buildRect(new Point(10,10), new Point(20,20)); 
rect.printRect(); 

System.out.printlin("---------- ")5 


System.out.print("Calling buildRect w/1 point (10,10),"); 
System.out.printin(" width (50) and height (50)"); 


rect.buildRect(new Point(10,10), 50, 50); 
rect.printRect(); 
System.out.printlin("---------- ae 


H ere’s the output of this] ava program: 


| Calling buildRect with coordinates 25,25 50,50: 
Output MyRect: <25, 25, 50, 50> 


Calling buildRect w/points (10,10), (20,20): 
MyRect: <10, 10, 20, 20> 


Calling buildRect w/1 point (10,10), width (50) and height (50) 
MyRect: <10, 10, 60, 60> 


Asyou can see from this example, all the buildrRect() methods work based on the arguments 
with which they are called. You can define as many versions of amethod as you need to in your 
own classes to implement the behavior you need for that class. 


Constructor Methods 


In addition to regular methods, you can also defineconstructor methodsin your class definition. 


NEWe- Aconsructor method isaspecial kind of method that determineshow an objectisinitialized 
TERM when it’s created. 


Unlike regular methods, you can’t call a constructor method by calling it directly; instead, 
constructor methods are called by J ava automatically. H ere’s how it works: when you use new 
to create a new instance of a class, | ava does three things: 


Allocates memory for the object 
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(J Initializes that object’s instance variables, either to their initial values or to a default (a 
for numbers, nui1 for objects, false for booleans) 


_| Calls the class's constructor method (which may be one of several methods) 


If aclassdoesn’t haveany special constructor methodsdefined, you'll still end up with an object, 
but you'll have to set its instance variables or call other methods that object needs to initialize 
itself to that object afterward. All the examples you've created up to this point have behaved like 
this. 


By defining constructor methods in your own classes, you can set initial values of instance 
variables, call methods based on those variables or call methods on other objects, or calculate 
initial properties of your object. You can also overload constructors, as you would regular 
methods, to create an object that has specific properties based on the argumentsyou giveto new. 


B asic Constructors 
Constructors look a lot like regular methods, with two basic differences: 


Constructors always have the same name as the class. 
Constructors don’t havea return type. 


For example, Listing 7.3 shows a simple class called Person, with a constructor that initializes 
its instance variables based on the arguments to new. T he class also includes amethod for the 
object to introduce itself, and amain() method to test each of these things. 


Type Listing 7.3. The Person class. 


class Person { 
String name; 
int age; 


Person(String n, int a) { 
name = n; 
age = a; 


} 


void printPerson() { 
System.out.print("Hi, my name is " + name); 
System.out.printin(". I am " + age + " years old."); 


} 


public static void main (String args[]) { 
Person p; 


p = new Person("Laura", 20); 
p.printPerson(); 
System.out.printin("-------- i 
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p = new Person("Tommy", 3); 

p.printPerson(); 

System.out.printin("-------- ")3 
} 


H ere’s the output for this example program: 


0 ut Hi, my name is Laura. I am 20 years old. 


Calling Another Constructor 


Someconstructors you writemay bea superset of another constructor defined in your class; that 
is, they might have the same behavior plus alittle bit more. Rather than duplicating identical 
behavior in multipleconstructor methodsin your class, it makes senseto be ableto just call that 
first constructor from inside the body of thesecond constructor. J ava provides a special syntax 
for doing this. T o call aconstructor defined on the current class, use this form: 


this(arg1, arg2, arg3...); 


The arguments to this are, of course, the arguments to the constructor. 


Overloading Constructors 


Like regular methods, constructors can also take varying numbers and types of parameters, 
enabling you to create your objects with exactly the properties you want it to have, or for it to 
be able to calculate properties from different kinds of input. 


For example, the buildrect () methods you defined in themyrect Classearlier today would make 
excellent constructors, because what they’re doing isinitializing an object’sinstance variablesto 
the appropriate objects. So, instead of the original buildrect() method you had defined (which 
took four parameters for the coordinates of the corners), you can create a constructor instead. 
Listing 7.4 shows anew class, called myrect2, that has all the same functionality of the original 
MyRect, except with overloaded constructor methods instead of the buildrRect() method. 


Type Listing 7.4. The myRect2 class (with constructors). 


import java.awt.Point; 
Class MyRect2 { 

int x1 = Q; 

int y1 = 0; 


continues 
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Listing 7.4. continued 


Q; 
Q; 


int x2 = 
int y2 = 
MyRect2(int x1, int y1, int x2, int y2) { 

this.x1 x1; 

this.y1 y1; 

this.x2 x2; 

this.y2 y2; 


} 


MyRect2(Point topLeft, Point bottomRight) { 
x1 topLeft.x; 
y1 topLeft.y; 
x2 = bottomRight.x; 
y2 = bottomRight.y; 


MyRect2(Point topLeft, int w, int h) { 
x1 topLeft.x; 
y1 topLeft.y; 
x2 (x1 + w); 
y2 = (y1 +h); 


void printRect() { 
System.out.print("MyRect: <" + x1 +", "+ y1); 
System.out.printin(", "+ x2 + ", "+ y2 + ">"); 


} 


public static void main (String args[]) { 
MyRect2 rect; 


System.out.printin("Calling MyRect2 with coordinates 25,25 50,50:"); 
rect = new MyRect2(25, 25, 50,50); 

rect.printRect(); 

System.out.printin("---------- an 


System.out.printin("Calling buildRect w/points (10,10), (20,20):"); 
rect= new MyRect2(new Point(10,10), new Point(20, 20) ); 
rect.printRect(); 

System.out.printin("---------- a 


System.out.print("Calling buildRect w/1 point (10,10),"); 
System.out.printin(" width (50) and height (50)"); 

rect = new MyRect2(new Point(10,10), 50, 50); 
rect.printRect(); 

System.out.printin("---------- ")3 


H ere’s the output for this example program (it’s the same output from the previous example; 
only the code to produce it has changed): 
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Calling MyRect2 with coordinates 25,25 50,50: 
Output MyRect: <25, 25, 50, 50> 


Calling buildRect w/points (10,10), (20,20): 
MyRect: <10, 10, 20, 20> 


Calling buildRect w/1 point (10,10), width (50) and height (50) 
MyRect: <10, 10, 60, 60> 


Overriding Methods 


W hen you classamethod in an object, J avalooksfor that method definition in thecorrect object, 
and if it doesn’t find one, it passes the method call up the class hierarchy until a method 
definition is found. M ethod inheritance enables you to define and use methods repeatedly in 
subclasses without having to duplicate the code itself. 


H owever, theremay betimeswhen you want an object to respond to thesame methods but have 
different behavior when that method is called. In this case, you can override that method. 
O verriding a method involves defining a method in a subclass that has the same signature as a 
method in asuperclass. Then, when that method is called, the method in the subclass is found 
and executed instead of the onein the superclass. 


Creating Methods 
that Override E xisting Methods 


To overridea method, all you haveto do is createa method in your superclass that hasthesame 
signature (name, return type, and parameter list) as a method defined by one of your class’s 
superclasses. Because Java executes the first method definition it finds that matches the 
signature, this effectively “hides” the original method definition. H ere’s a simple example 
Listing 7.5 shows a simple class with a method called printme(), which prints out the name of 
the class and the values of its instance variables. 


Type Listing 7.5. The PrintClass Class. 
class PrintClass { 
int x = Q; 
int y = 1; 


void printMe() { 
System.out.printin("X is "+x +", Yis "+ y); 
System.out.println("I am an instance of the class " + 
this.getClass().getName()); 
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Listing 7.6 shows a class called printsubclass that is a subclass of (extends) PrintClass. The 
only differencebetween printClass and PrintSubClass isthat thelatter hasaz instance variable. 


Type Listing 7.6. The PrintSubClass Class. 


class PrintSubClass extends PrintClass { 
int z = 3; 


public static void main (String args[]) { 
PrintSubClass obj = new PrintSubClass(); 
obj.printMe() ; 


H ere’s the output from printSubClass: 


X is @, Y is 1 
Output I am an instance of the class PrintSubClass 


A , i In themainc) method of PrintSubClass, you create a PrintSubClass Object and call the 
Ah yas printme() method. N otethat printsubclass doesn’t define thismethod, so J avalooks for 
it in each of PrintsubClass’s superclasses— and finds it, in this case, in Printclass. 
Unfortunately, because printme() isstill defined in printclass, it doesn’t print the z instance 


variable. 


N ow, let’s create a third class. printSubClass2 is nearly identical to printsubClass, but you 
override the printme() method to include the z variable. Listing 7.7 shows this class. 


‘Type Listing 7.7. The printSubClass2 Class. 


class PrintSubClass2 extends PrintClass { 
int z = 3; 


void printMe() { 
System.out.printin("x is "+x+", yis "+yt 
", zis "+ 2); 
System.out.printin("I am an instance of the class " + 
this.getClass().getName()); 


} 


public static void main (String args[]) { 
PrintSubClass2 obj = new PrintSubClass2() ; 


obj.printMe() ; 


N ow, when you instantiate this class and call the printme() method, the version of printme() 
you defined for this classis called instead of the onein thesuperclassprintclass (as you can see 


in this output): 


|} x is 0, y is 1, z is 3 
Output I am an instance of the class PrintSubClass2 
] 


Calling the Original Method 


U sually, there are two reasons why you want to overridea method that a superclass has already 
implemented: 


To replace the definition of that original method completely 
To augment the original method with additional behavior 


You'vealready learned about thefirst one by overridingamethod and giving that method anew 
definition, you’ve hidden the original method definition. But sometimes you may just want to 
add behavior to the original definition rather than erase it altogether. T hisis particularly useful 
where you end up duplicating behavior in both the original method and the method that 
overridesit; by beingableto call the original method in the body of theoverridden method, you 
can add only what you need. 


To call theoriginal method from insidea method definition, usethe super keyword to passthe 
method call up the hierarchy: 


void myMethod (String a, String b) { 
// do stuff here 
super.myMethod(a, b); 
// maybe do more stuff here 


} 


The super keyword, like the this keyword, is a placeholder for this class's superclass. You can 
use it anywhere you want to refer to your superclass rather than to the current class. 


For example, Listing 7.8 shows those printme() methods used in the previous example. 


Type Listing 7.8. The printme methods. 


// from PrintClass 
void printMe() { 
System.out.printin("X is "+x +", Yis "+ y); 
System.out.println("I am an instance of the class" + 
this.getClass().getName()); 


} 


//from PrintSubClass2 
void printMe() { 
System.out.printin("X is "+x +", Yis "+y+", Zis "+ Zz); 
System.out.printlin("I am an instance of the class " + 
this.getClass().getName()); 
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Rather than duplicating most of the behavior of the superclass’s method in thesubclass, you can 
rearrange the superclass’s method so that additional behavior can easily be added: 


// from PrintClass 

void printMe() { 
System.out.printlin("I am an instance of the class" + 

this.getClass().getName()); 

System.out.printin("X is " + x); 
System.out.printin("Y is " + y); 
} 

} 


Then, inthesuperclass, when you overrideprintme, you can merely call theoriginal method and 
then add the extra stuff: 


// From PrintSubClass2 

void printMe() { 
super.printMe() ; 
System.out.printin("Z is " + z); 
t 

} 


H ere’s the output of calling printme() on an instance of the superclass: 


I am an instance of the class PrintSubClass2 
Output «so 

Y is 1 

Z 


is 3 


Overriding Constructors 


Constructors cannot technically be overridden. Because they always have thesame nameas the 
current class, you’re always creating new constructorsinstead of inheriting the ones you've got. 
M uch of the time, this is fine, because when your class’s constructor is called, the constructor 
with the same signature for all your superclass is also called, so initialization of all the parts of 
a class you inherit can happen. 


H owever, when you're defining constructors for your own class, you may want to change how 
your object is initialized, not only by initializing the information your class adds, but also to 
change the information that is already there. You can do this by explicitly calling your 
superclass’s constructors. 


To call aregular method in a superclass, you use super .methodname (arguments). Because with 
constructors you don’t havea method name to call, however, you haveto usea different form: 


super(arg1, arg2, ...)} 


Similar to using this(...) in aconstructor, super(...) Calls the constructor method for the 
immediate superclass (which may, in turn, call the constructor of its superclass, and so on). 


For example, Listing 7.9 shows a class called NamedPoint, which extends the class point from 
Java’sawt package. T hepoint classhas only oneconstructor, which takesan x and ay argument 
and returnsa Point object. NamedPoint hasan additional instance variable (a string for thename) 
and defines a constructor to initialize x, y, and the name. 


Type Listing 7.9. The NamedPoint class. 


1: import java.awt.Point; 


: class NamedPoint extends Point { 
String name; 


NamedPoint(int x, int y, String name) { 


2 

3 

4 

5 

6: super(X,y)3 
7: this.name = name; 
8 

9 


®) Theconstructor defined here for NamedPoint (lines 6 through 8) calls point’s constructor 
Analygs method to initialize Point’s instance variables (x and y). Although you can just as easily 
initialize x and y yourself, you may not know what other things Point isdoing to initialize 
itself, so it’s always a good idea to pass constructors up the hierarchy to make sure everything 
is set up correctly. 


Finalizer Methods 


Finalizer methods are like the opposite of constructor methods; whereas a constructor method 
is used to initialize an object, finalizer methods are called just before the object is garbage 
collected and its memory reclaimed. 


To create a finalizer method, include a method with the following signature in your class 
definition: 

void finalize() { 

oe 


Inside the body of that tinalize() method, include any cleaning up you want to do for that 
object. 


Before you start using finalizer methods extensively in your J ava programs, however, be aware 
that finalizer methods haveseveral very important restrictions. First of all, the finalizer method 
isnot guaranteed to becalled until theobject’smemory isactually reclaimed, which may besome 
time after you've renoved all references to that object. 
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You can alwayscall the finalize ) method yourself at any time it’sjust aplain method likeany 
other. H owever, Calling finalize() does not trigger an object to be garbage-collected. O nly 
removing all references to an object will causeit to be marked for deleting, and even then, J ava 
may or may not call the finalize () method itself— regardless of whether or not you've already 
called it. 


Finalizer methods are best used for optimizing the removal of an object— for example, by 
removing referencesto other objects, by cleaning up thingsthat object may havetouched, or for 
other optional behaviors that may make it easier for that object to be removed. In most cases, 
you may not need to use finalize() at all. 


Summary 


T oday, you learned all kinds of techniquesfor using, reusing, defining, and redefining methods. 
You learned how to overload a method name so that the same method can have different 
behaviors based on the arguments with which it’s called. You learned about constructor 
methods, which areused to initializea new object when it’s created. Y ou learned about method 
inheritanceand how to overridemethodsthat havebeen defined in aclass’ssuperclasses. Finally, 
you learned about finalizer methods, that can beused to clean up after an object just beforethat 
object is garbage-collected and its memory reclaimed. 


Congratulations on completing your first week of T each Y oursdf J ava in 21 D ays! Starting next 
week, you'll apply everything you've learned this week to writing J ava applets and to working 
with moreadvanced conceptsin putting together | ava programsand working with thestandard 
J ava class libraries. 


Q&A 


Q | created two methods with the following signatures: 
int total(int arg1, int arg2, int arg3) {...} 
float total(int arg1, int arg2, int arg3) {...} 
The Java compiler complains when I try to compile the class with these method 
definitions. But their signatures are different— what have! done wrong? 


A Method overloading in J ava works only if the parameter lists are different— either in 
number or type of arguments. Return type is not relevant for method overloading. 
Think about it— if you had two methods with exactly the same parameter list, how 
would Java know which one to call? 
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You described using the this() method (this(arg, arg, ...)) to call a construc- 
tor from inside another constructor. Are you limited to using the this() method 
call inside constructors? 


No, you can use that method anywhere to refer to the current object’s constructor. 
Onan existing object, calling a constructor is an easy way to reinitialize that object 
back to its default state (or to change it to have the state that you want it to have). 


Can I overload overridden methods (that is, can | create methods that have the 
same name as an inherited method, but a different parameter list)? 


Sure! As long as a parameter lists vary, it doesn’t matter whether you've defined a new 
method name or one that you've inherited from a superclass. 


| created a finalizer method to decrement a class variable and print a message 
when my object gets garbage-collected. This way | can keep track of how many 
objects of this class are running at any given time. But sometimes finalize) gets 
called and sometimes it doesn’t. H ow can | guarantee that fina1ize() will be 
called and my program will operate correctly? 


finalize() is provided as a convenience, to give an object a chance to clean up after 
itself. finalize() May or may not be called on any given object before it is garbage- 
collected, so you should not depend on its existence; you should be using finalize() 
only to provide program optimizations. 

If you absolutely require that an object perform some operation before that object gets 
garbage-collected, you should create a specific method other than finalize() and 
explicitly call that method before discarding references to that object. 
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Including an applet on a W eb page 
Passing parameters 

Graphics, Fonts, and Color 

Graphics primitives 

The color Class 

Simple Animation and T hreads 

paint() and repaint () 

Reducing animation flicker 

stop and start 

M ore Animation, Images, and Sound 
Scaling options, executing sound effectively 
D ouble-buffering 

M anaging Simple Events and Interactivity 
MouseDown and MouseUp 

T he] ava event handler 
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Week 2 ata Glance 


_] User Interfaces with the] ava Abstract W indowing T oolkit 

Canvases, text components, widgets, and window construction components 
_] Windows, N etworking, and Other Tidbits 

Programming menus and creating links inside applets 
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® DAY @ 
Java Applet Basics 


M uch of J ava’s current popularity has come about because of | ava-capable W orld W ide W eb 
browsers and their support for applets: small programs that run inside a W eb page and can be 
used to create dynamic, interactive W eb designs. Applets, as! noted at the beginning of this 
book, are written in the] ava language, and can be viewed in any browser that supports J ava, 
including Sun’sH ot} ava and N etscape’s N avigator 2.0. Learning how to create appletsis most 
likely the reason you bought this book, so let’s waste no more time 


Last week, you focused on learning about the] avalanguageitself, and most of thelittleprograms 
you created were J ava applications. T his week, now that you have the basics down, you move 
on to creating and using applets, which includes a discussion of many of the classes in the 
standard J ava class library. 


Today, you'll start with the basics: 


A small review of differences between J ava applets and applications 


Getting started with applets: the basics of how an applet works and how to create your 
own simple applets 


Including an applet on a W eb page by using the <appceT> tag, including the various 
features of that tag 


“| Passing parameters to applets 


H ow Applets and Applications Are 
Different 


Although you explored the differences between J ava applications and J ava applets in the early 
part of this book, let’s review them. 


In short, J ava applications are stand-alone] ava programs that can berun by using just the] ava 
interpreter, for example, from a command line. M ost everything you've used up to this point 
in the book has been aJ ava application, albeit a simple one. 


Java applets, however, arerun from insideaW orld W ideW eb browser. A referenceto an applet 
is embedded in a Web page using a special HT ML tag. When a reader, using a] ava-aware 
browser, loads a W eb page with an applet in it, the browser downloads that applet from aW eb 
server and executes it on the local system (the one the browser is running on). 


Because ] ava applets run inside the] ava browser, they have access to the same capabilities that 
the browser has: sophisticated graphics, drawing, and image processing packages; user interface 
elements; networking; and event handling. J ava applications can also take advantage of these 
features, but they don’t requirethem (you'll learn how to create] avaapplicationsthat useapplet- 
like graphics and UI features on D ay 14). 
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T headvantages applets haveover applicationsin termsof graphicsand U | capabilities, however, 
are hampered by restrictions on what applets can do. Given the fact that J ava applets can be 
downloaded from anywhere and run on aclient’s system, restrictions are necessary to prevent 
an applet from causing system damage or security breaches. W ithout these restrictionsin place, 
Java applets could be written to contain viruses or trojan horses (programs that seem friendly 
but do somesort of damage to thesystem), or be used to compromise the security of the system 
that runs them. T he restrictions on what an applet can do include the following: 


() Applets can’t read or write to the reader’s file system, except in specific directories 
(which are defined by the user through an access control list that, by default, is 
empty). Some browsers may not even allow an applet to read or write to the file 
system at all. 

[) Applets can’t usually communicate with a server other than the one that had originally 

stored the applet. (T his may be configurable by the browser; however, you should not 

depend on having this behavior available.) 

Applets can’t run any programs on the reader’s system. For U nix systems, this includes 

forking a process. 

Applets can’t load programs native to the local platform, including shared libraries 

such as DLLs. 


In addition, J ava itself includes various forms of security and consistency checking in the] ava 
compiler and interpreter to prevent unorthodox useof thelanguage (you'll learn moreabout this 
on Day 21). This combination of restrictions and security features make it more difficult for a 
rogue J ava applet to do damage to the client’s system. 


Note: T he most important words in the last sentence are “more difficult.” T hese 
restrictions can prevent most of the more obvious ways of trying to cause damage 
to aclient’s system, but it’s impossible to be absolutely sure that a clever program- 
mer cannot somehow work around those restrictions. Sun has asked the N et at 
large to try to break J ava’s security and to create an applet that can work around the 
restrictions imposed on it. If aholeis found, Sun will patch it. You'll learn about 
more Issues in J ava security on D ay 21. 


Creating Applets 


For the most part, all the Java programs you've created up to this point have been Java 
applications— simple programs with a single main() method that created objects, set instance 
variables, and ran methods. Today and in the days following, you'll be creating applets 
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exclusively, so you should have a good grasp of how an applet works, the sorts of features an 
applet has, and whereto start when you first create your own applets. W ithout further ado, let’s 
get on with it. 


To create an applet, you create a subclass of the class Applet, in the java.applet package. T he 
Applet Class provides behavior to enable your applet not only to work within the browser itself, 
but also to take advantage of the capabilities of AW T to includeU! edements, to handle mouse 
and keyword events, and to draw to thescreen. Although your applet can haveasmany “helper” 
classes as it needs, it’sthe main applet class that triggers the execution of the applet. T hat initial 
applet class always has a signature like this: 


public class myClass extends java.applet.Applet { 


} 


N otethepublic keyword. J avarequiresthat your applet subclass bedeclared public. Again, this 
istrue only of your main applet class; any helper classes you create can be public OF private as 
you wish. Public, private, and other forms of access control are described on D ay 15. 


When Java encounters your applet in a Web page, it loads your initial applet class over the 
network, aS well asany other helper classes that first class uses. U nlike with applications, where 
Javacallsthemain() method directly on your initial class, when your applet isloaded, J avacreates 
an instance of that class, and all the system-based methods are sent to that instance. D ifferent 
applets on the same page, or on different pages that use the same class, use different instances, 
so each one can behave differently from other applets running on the same system. 


Major Applet Activities 


To create a basic Java application, your class has to have one method, main), with a specific 
signature. Then, when your application starts up, main is executed, and from main you can set 
up the behavior that your programs need. Applets are similar but more complicated. Applets 
have many different activities that correspond to various major events in the life cycle of the 
applet— for example initialization, painting, or mouseevents. Each activity hasacorresponding 
method, so when an event occurs, the browser or other Java-capable tool calls those specific 
methods. 


By default, none of those activity methods have any definitions; to provide behavior for those 
events you must override the appropriate method in your applet’s subclass. You don’t have to 
override all of them, of course; different applet behavior requires different methods to be 
overridden. 


You'll learn about the various important methods to override as the week progresses, but, fora 
general overview, here are five of the more important methods in an applet’s execution: 
initialization, starting, stopping, destroying, and painting. 


Initialization 

Initialization occurs when the applet is first loaded (or reloaded). Initialization can include 
creating the objects it needs, setting up an initial state loading images or fonts, or setting 
parameters. To provide behavior for the initialization of your applet, override the init() 
method: 


public void init() { 


} 


Starting 

After an applet is initialized, it is started. Starting can also occur if the applet was previously 
stopped. For example, an applet is stopped if the reader follows alink to a different page, and 
it isstarted again when thereader returnsto thispage. N otethat starting can occur several times 
during an applet’s life cycle, whereas initialization happens only once. To provide startup 
behavior for your applet, override the start() method: 


public void start() { 


} 


Functionality that you put in thestart() method might includestarting up a thread to control 
theapplet, sending the appropriate messages to helper objects, or in someway telling the applet 
to begin running. You'll learn more about starting applets on Day 10. 


Stopping 

Stopping and starting go hand in hand. Stopping occurs when the reader leaves the page that 
contains a currently running applet. By default, when the reader leaves a page, the applet 
continues running, using up system resources. By overriding stop, you can suspend execution 
of the applet and then restart it if the applet is viewed again. T o stop an applet’s execution, use 
the stop) method: 


public void stop() { 


} 


D estroying 

Destroying sounds more violent than it is. D estroying enables the applet to clean up after itself 
just beforeit or thebrowser exits— for example, to kill any running threadsor to releaseany other 
running objects. Generally, you won't want to override destroy unless you have specific 
resources that need to bereleased— for example, threads that the applet has created. T o provide 
clean up behavior for your applet, override the destroy() method: 
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public void destroy() { 


} 


Technical N ote: H ow iS destroy() different from finalize(), which was described 
on Day 7? First, destroy() applies only to applets. finalize() isa more general- 
purpose way for asingle object of any type to clean up after itself. 

The other difference is that destroy() is always called when the applet has finished 
executing, either because the browser is exiting or because the applet is being 
reloaded. finalize) isnot guaranteed to be executed. 


Painting 

Painting is how an applet actually draws something on the screen, be it text, a line, a colored 
background, or an image. Painting can occur many hundreds of times during an applet’s life 
cycle— for example, once after the applet isinitialized, if the browser is placed behind another 
window on the screen and then brought forward again, if the browser window is moved to a 
different position on the screen, or perhaps repeatedly in the case of animations. You override 
the paint() method for your applet to have an actual appearance on the screen. T he paint() 
method looks like this: 


public void paint(Graphics g) { 
} 


N otethat unliketheother major methodsin thissection, paint () takesan argument, an instance 
of theclasscraphics. T hisobject iscreated and passed to paint by thebrowser, so you don’t have 
to worry about it. H owever, you will have to make sure that the Graphics Class (part of the 
java.awt package) gets imported into your applet code, usually through an import statement at 
the top of your J ava file 


import java.awt.Graphics; 


A Simple Applet 


On Day 2, you created asimple applet called H dloAgainA pplet (this was the one with thebig 
red Hello Again). T here, you created and used that applet as an example of creating a subclass. 
Let’s go over the code for that applet again, thistime looking at it slightly differently in light of 
the things you just learned about applets. Listing 8.1 shows the code for that applet. 


Type Listing 8.1. The Hello Again applet. 


import java.awt.Graphics; 


import java.awt.Font; 
import java.awt.Color; 


1 
2 
3 
4: 
5: public class HelloAgainApplet extends java.applet.Applet { 
6: 
7 Font f = new Font("TimesRoman",Font.BOLD, 36) ; 

8 

9 


public void paint(Graphics g) { 


10: g.setFont(f) ; 

11: g.setColor(Color.red) ; 

12: g.drawString("Hello again!", 5, 50); 
13: } 

14: } 


Because the applet doesn’t actually execute (all it does is print a couple of words to the 
screen), and there's not really anything to initialize, you don’t need astart() OF astop() 
or an init) method. 


Analysis Thisapplet overrides paint), oneof themajor methods described in the previous section. 
| 


T hepaint method iswherethe real work of this applet (what little work goes on) really occurs. 
The Graphics object passed into the paint) method holds that graphics state— that is, the 
current features of thedrawing surface Lines 10 and 11 set up thedefault font and color for this 
graphics state (here, the font object help in the + instance variable, and an object representing 
the color red that’s stored in the color class's variable red). 


Line12 then drawsthestring "Hello Again!" by usingthecurrent font and color at the position 
5, 50. N otethat theo point for y is at thetop left of the applet’s drawing surface, with positive 
y Moving downward, so 5a is actually at the bottom of the applet. Figure 8.1 shows how the 
applet’s bounding box and the string are drawn on the page. 


Figure 8.1. va 
Drawing the apple. 


50 


ello again! 
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Including an Applet on a Web Page 


After you create a class or classes that contain your applet and compile them into class files as 
you would any other Javaprogram, you have to create a W eb page that will hold that applet by 
using the HT ML language. T here is a special HT M L tag for including applets in W eb pages; 
Java-capable browsers usetheinformation contained in that tagto locatethe compiled classfiles 
and execute the applet itself. In thissection, you'll learn about how to put J avaappletsin aW eb 
page and how to serve those files to the W eb at large. 


Note: T he following section assumes you have at least a passing understanding of 
writing HT ML pages. If you need help in this area, you may find the book T each 
Yoursaf Web Publishing with HTML in 14 Daysuseful. It is also from Sams.N et 
(and also written by one of the authors of this book). 


The <APPLET>Tag 


Toincludean applet on a W eb page, use the <appLet> tag. <APPLET> iS a Special extension to 
HTML for including applets in W eb pages. Listing 8.2 snows a very simple example of a W eb 
page with an applet included in it. 


Type Listing 8.2. A simple HTML page. 


<HTML> 

<HEAD> 

<TITLE>This page has an applet on it</TITLE> 
</HEAD> 

<BODY> 

<P>My second Java applet says: 

<BR> 

<APPLET CODE="HelloAgainApplet.class" WIDTH=200 HEIGHT=50> 
There would be an applet here if your browser 
10: supported Java. 

11: </APPLET> 

12: </BODY> 

13: </HTML> 


OONOOABRWN 


There are three things to note about the <appLet> tag in this page: 


(| Thecope attribute indicates the name of the class file that loads this applet, including 
the .class extension. In this case, the class file must bein the same directory as this 
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HTML file. To indicate applets arein a different directory, use copeBase, described 
later today. 


WIDTH and HEIGHT are required and used to indicate the bounding box of the applet— 
that is, how big a box to draw for the applet on the W eb page. Be sure you set w1DTH 
and HEIGHT to bean appropriate size for the applet; depending on the browse, if your 
applet draws outside the boundaries of the space you've given it, you may not be able 
to see or get to those parts of the applet outside the bounding box. 


The text between the <AppLeT> and </appLeT> tags is displayed by browsers that do 
not understand the <appLet> tag (which includes most browsers that are not J ava- 
capable). Because your page may be viewed in many different kinds of browsers, it isa 
very good idea to include alternate text here so that readers of your page who don’t 
have J ava will see something other than a blank line. H ere, you include a simple 
statement that says There would be an applet here if your browser supported 
Java. 


N ote that the <app_et> tag, like the <1me> tag, isnot itself a paragraph, so it should be enclosed 
inside a more general text tag, such as <p> or one of the heading tags (<H1> , <H2>, and so on). 


Testing the Result 


N ow with aclass fileand an HT ML file that refers to your applet, you should be able to load 
that HTML fileinto your J ava-capable browser (using either the O pen Local... dialog iten or 
afileU RL, or byindicatingthefilenameon acommand line). T hebrowser loadsand parsesyour 
HTML file, and then loads and executes your applet class. 


Figure 8.2 shows the H ello Again applet, in case you've forgotten what it looks like. 


Figure 8.2. 
TheH dlo Again apple. 


Hello again! 


Making J ava Applets Available to the Web 


After you have an applet and an HTML file, and you’ve verified that everything is working 
correctly on your local system, the last step is making that applet available to the W orld Wide 
W eb at large so that anyone with aJ ava-capable browser can view that applet. 
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J ava applets are served by aW eb server thesameway that H TM L files, images, and other media 
are. You don’t need special server software to make} ava applets availableto the W eb; you don’t 
even need to configure your server to handle} ava files. If you havea W eb server up and running, 
or spaceon aW eb server availableto you, all you haveto do ismoveyour H T ML and compiled 
class files to that server, as you would any other file 


If you don’t haveaW eb server, you haveto rent spaceon oneor set oneup yourself. (W eb server 
setup and administration, as well as other facets of W eb publishing in general, are outside the 
scope of this book.) 


More About the <APPLET>Tag 


In its simplest form, by using coDE, w1DTH, and HETGHT, the <AppLeT> tag merely creates a space 
of the appropriate size and then loads and plays the applet in that space. T he <appLet> tag, 
however, doesinclude several attributes that can help you better integrate your applet into the 
overall design of your W eb page. 


Note: T he attributes available for the <appLet> tag are almost identical to those for 
the HTML <1me> tag. 


ALIGN 


T heatien attribute defines how the applet will be aligned on the page. T his attribute can have 
one of nine values: LEFT, RIGHT, TOP, TEXTTOP, MIDDLE, ABSMIDDLE, BASELINE, BOTTOM, and 
ABSBOTTOM. 


Inthe case of ALIGN=LEFT and ALIGN=RIGHT, theapplet isplaced at theleft or right margins of the 
page, respectively, and all text following that applet flowsin the space to the right or left of that 
applet. T he text will continue to flow in that space until the end of the applet, or you can use 
aline break tag (<pr>) with thecLear attributeto start the left line of text below that applet. T he 
cLear attribute can have one of three values: cLear=LerT starts the text at the next clear left 
margin, CLEAR=RIGHT Coesthesamefor theright margin, and cLear=aL_ startsthetext at thenext 
line where both margins are clear. 


For example, here’s a snippet of HT ML code that aligns an applet against the left margin, has 
some text flowing alongside it, and then breaks at the end of the paragraph so that the next bit 
of text starts below the applet: 
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<P><APPLET CODE="HelloAgainApplet" WIDTH=300 HEIGHT=200 
ALIGN=LEFT>Hello Again!</APPLET> 

To the left of this paragraph is an applet. It's a 
simple, unassuming applet, in which a small string is 
printed in red type, set in 36 point Times bold. 

<BR CLEAR=ALL> 

<P>In the next part of the page, we demonstrate how 
under certain conditions, styrofoam peanuts can be 

used as a healthy snack. 


Figure 8.3 shows how this applet and the text surrounding it might appear in a J ava-capable 
browser. 


Figure 8.3. Netscape: Applet Alignment 


An applet aligned left. To the left of this paregreph is an epplet. Its an 
let, in which a small string is printed 


2 ayer peaa nes joint Times bold. 
Hello again! *****r 


Inthe next part of the page, we demonstrate how under certain conditions, styrofoam peanuts can 
be used as a healthy snack. 


For smaller applets, you may want to include your applet within asinglelineof text. T o do this, 
there are seven values for aLten that determine how theapplet is vertically aligned with thetext: 


ALIGN=TEXTTTOP aligns the top of the applet with the top of the tallest text in the line 
ALIGN=TOP aligns the applet with the topmost item in the line (which may be another 
applet, or an image, or the top of the text). 

ALIGN=ABSMIDDLE aligns the middle of the applet with the middle of the largest item in 
the line 

ALIGN=MIDDLE aligns the middle of the applet with the middle of the baseline of the 
text. 

ALIGN=BASELINE aligns the bottom of the applet with the baseline of the text. 
ALIGN=BASELINE IS the Same aS ALIGN=BOTTOM, Dut ALIGN=BASELINE iS amore descriptive 
name. 

ALIGN=ABsBOTTOM aligns the bottom of the applet with the lowest item in the line 
(which may be the baseline of the text or another applet or image). 


Figure 8.4 shows the various alignment options, where the line is an image and the arrow isa 
small applet. 
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Figure 8.4. ; ; ; me 
Applet alignment options | Middle of Text and Line aligned, arrow varies: 


ign: Top > Text Top > 


Top of Text and Lime aligned, arrow varies: 


ign: Absolute Middle Align: Middle > 


Top of Text and Lime aligned, arrow varies: 


: Baseline/Bottom ; Align: Absolute Bottom 


HSPACE and VSPACE 


T heuspace and vspace attributes areused to set theamount of space, in pixels, between an applet 
and its surrounding text. Hspace controls the horizontal space (the space to the left and right of 
the applet). vspace controls the vertical space (the space above and below). For example, here's 
that sample snippet of HTML with vertical space of 10 and horizontal space of so: 


<P><APPLET CODE="HelloAgainApplet" WIDTH=300 HEIGHT=200 
ALIGN=LEFT VSPACE=10 HSPACE=50>Hello Again!</APPLET> 

To the left of this paragraph is an applet. It's a 
simple, unassuming applet, in which a small string is 
printed in red type, set in 36 point Times bold. 

<BR CLEAR=ALL> 

<P>In the next part of the page, we demonstrate how 
under certain conditions, styrofoam peanuts can be 

used as a healthy snack. 


The result in a typical Java browser might look like that in Figure 8.5. 
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Figure 8.5. 
Vertical and horizontal 
space. 


= he tscape: Applet Alignment 


To the left of this paragraph is an applet. Its an 
unassuming applet, in which a small string is 
printed in red type, set in 36 point Times bold. 


Hello again! 


inthe next part of the page, we demonstrate how under certain conditions, styrofoam peanuts can 
be used as a healthy snack. 


CODE and CODEBASE 


cone is used to indicate the name of the class file that holds the current applet. If cope is used 
alone in the <appLeT> tag, the class file is searched for in the same directory asthe HT ML file 
that references it. 


If you want to store your class files in a different directory than that of your HT M L files, you 
haveto tell the} ava-capable browser whereto find thoseclassfiles. T o do this, you USeCcoDEBASE. 
cope contains only the name of the class file; copEBase contains an alternate pathname where 
classesare contained. For example, if you storeyour classfilesin adirectory called /classes, which 
isin the same directory as your HT M L files, copepase is the following: 


<APPLET CODE="myclass.class" CODEBASE="classes" 
WIDTH=100 HEIGHT=100> 


P assing Parameters to Applets 


With Javaapplications, you can pass parametersto your main() routine by using arguments on 
the command line. You can then parse those arguments inside the body of your class, and the 
application acts accordingly based on the arguments it is given. 


Applets, however, don’t havea command line. H ow do you passin different arguments to an 
applet? Applets can get different input from the HTML file that contains the <appLet> tag 
through the use of applet parameters. T o set up and handle parameters in an applet, you need 
two things: 


A special parameter tag in the HTML file 
Codein your applet to parse those parameters 
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Applet parameters come in two parts: aname, which is simply aname you pick, and a value, 
which determines the value of that particular parameter. So, for example, you can indicate the 
color of text in an applet by using a parameter with the name color and the value rea. You can 
determine an animation’s speed using a parameter with the name speed and the values. 


Inthe HTML fie that contains the embedded applet, you indicate each parameter using the 
<Param> tag, which has two attributes for thename and the value, called (surprisingly enough), 
NAME and vaLuE. T he <param> tag goes inside the opening and closing <aPPLeT> tags: 

<APPLET CODE="MyApplet.class" WIDTH=100 HEIGHT=100> 

<PARAM NAME=font VALUE="TimesRoman"> 

<PARAM NAME=size VALUE="36"> 

A Java applet appears here.</APPLET> 

T hisparticular exampledefinestwo parametersto theM yApplet applet: onewhosenameisfont 
and whose value is TimesRoman, and one whose name is size and whose value is 36. 


T hose parameters are passed to your applet when it is loaded. In the init() method for your 
applet, you can then get hold of those parameters by using the getParameter method. 
getParameter takes one argument— a string representing the name of the parameter you’re 
looking for— and returnsa string containing the corresponding value of that parameter. (Like 
arguments in J ava applications, all the parameter values are converted to strings.) To get the 
value of the font parameter from the HTML file, you might havea line such as this in your 
init() method: 


String theFontName = getParameter("font"); 


Note: T he names of the parameters as specified in <param> and the names of the 
parameters in getParameter Must match identically, including having the same 
upper and lower case. In other words, <PARAM= NAME="name"> IS different from 
<PARAM NAME="Name">. If your parameters are not being properly passed to your 
applet, make sure the parameter names match. 


N ote that if a parameter you expect has not been specified in the HTML file, getParameter 
returns nu11. M ost often, you will want to test for a nui1 parameter and supply a reasonable 
default: 

if (theFontName == null) 

theFontName = "Courier" 

Keep in mind also that because getParameter returnsstrings, if you want aparameter to besome 
other object or type, you haveto convert it yourself. T o parsethesize parameter from that same 
HTML fileand assign it to an integer variable called thesize, you might usethe following lines: 


int theSize; 
String s = getParameter("size"); 
if (s == null) 
theSize = 12; 
else theSize = Integer.parseInt(s); 
Get it? N ot yet? Let’s create an example of an applet that usesthistechnique. You'll modify the 
H elloAgainA pplet so that it says hello to a specific name, for example "Hello Bill" OF "Hello 
Alice". Thename is passed into the applet through an HT ML parameter. 


Let’s start with the original HelloAgainApplet Class: 


import java.awt.Graphics; 
import java.awt.Font; 
import java.awt.Color; 


public class MoreHelloApplet extends java.applet.Applet { 
Font f = new Font("TimesRoman",Font.BOLD, 36) ; 


public void paint(Graphics g) { 
g.setFont(f) ; 
g.setColor(Color.red) ; 
g.drawString("Hello Again!", 5, 50); 
} 
} 
T hefirst thing you need to add in thisclassisaplacefor thename. Becauseyou'll need that name 
throughout the applet, let’s add an instance variable for thename, just after the variable for the 


font: 
String name; 


To se avaluefor thename, you haveto get theparameter. T he best place to handle parameters 
to an applet is inside an init() method. The init) method is defined similarly to paint() 
(public, with no arguments, and areturn typeof void). M akesurewhen you test for a parameter 
that you test for avalueof nu11. T hedefault, in this case, if anameisn’t indicated, isto say hello 
tO "Laura": 
public void init() { 
this.name = getParameter("name") ; 

if (this.name == null) 

this.name = "Laura"; 

} 
O nelast thing to do now that you havethenamefrom theHT ML parametersisto modify the 
name so that it’s a complete string— that is, to tack "Hello " onto the beginning, and an 
exclamation point onto theend. You could do thisin the paint method just before printing the 
string to the screen. H ere it’s done only once, however, whereas in paint it’s done every time 
the screen isrepainted— in other words, it’sslightly more efficient to do it insideinit() instead: 


this.name = "Hello " + this.name + "!"; 
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And now, all that’s left is to modify the paint() method. The original drawstring method 
looked like this: 


g.drawString("Hello Again!", 5, 50); 


To draw the new string you have stored in the name instance variable, all you need to do is 
substitute that variable for the literal string: 


g.drawString(this.name, 5, 50); 
Listing 8.3 showsthefinal result of themoreHe11loAppiet Class. Compileit so that you haveaclass 
file ready. 


Type Listing 8.3. The moreHelloApplet Class. 


1: import java.awt.Graphics; 

2: import java.awt.Font; 

3: import java.awt.Color; 

4: 

5: public class MoreHelloApplet extends java.applet.Applet { 
6: 

Ti Font f = new Font("TimesRoman",Font.BOLD, 36) ; 
8: String name; 

9: 

10: public void init() { 

11: this.name = getParameter("name") ; 

12: if (this.name == null) 

13: this.name = "Laura"; 

14: 

15: this.name = "Hello " + this.name + "!"; 
16: } 

17: 

18: public void paint(Graphics g) { 

19: g.setFont (fF); 
20: g.setColor(Color.red); 
21: g.drawString(this.name, 5, 50); 
22: } 
23: } 


N ow, let’s create the HT M L file that contains this applet. Listing 8.4 shows a new W eb page 
for the M oreH elloApplet applet. 


Type Listing 8.4. The HTML file for the MoreH elloApplet applet. 


<HTML> 

<HEAD> 
<TITLE>Hello!</TITLE> 
</HEAD> 

<BODY> 


anon — 
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6: <P> 

7: <APPLET CODE="MoreHelloApplet.class" WIDTH=300 HEIGHT=50> 
8: <PARAM NAME=name VALUE="Bonzo"> 

9: Hello to whoever you are! 

10: </APPLET> 

11: </BODY> 

12: </HTML> 


L | —) Note the<appLet> tag, which points to the class file for the applet with the appropriate 

Analyss width and height (300 and so). Just below it (line 8) is the <parau> tag, which you use to 

~~ passin the name. H ere, the name parameter is simply name, and the value is the strong 
"Bonzo". 


Loading up thisHTML file produces the result shown in Figure 8.6. 


Figure 8.6. 
Theresult of 


M oreH dloApple, firs try. Hello Bonzo! 


Let's try a second example. Remember that in the code for M oreH elloApplet, if no name is 
specified, the default isthename "Laura". Listing 8.5 createsan HTML filewith no parameter 
tag for name. 


| ry Listing 8.5. Another HTML File for the 
| y | MoreH elloApplet applet. 


<HTML> 

<HEAD> 
<TITLE>Hello!</TITLE> 
</HEAD> 

<BODY> 

<P> 

<APPLET CODE="MoreHelloApplet.class" WIDTH=300 HEIGHT=50> 
Hello to whoever you are! 
</APPLET> 

</BODY> 

</HTML> 


=SOONOURWN = 


—_ 


H ere, becauseno namewas supplied, theapplet usesthe default, and theresult iswhat you might 
expect (see Figure 8.7). 
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Figure 8.7. 
The result of 


ao Hello Laura! 
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Summary 


Applets are probably the most common use of the Java language today. Applets are more 
complicated than many] avaapplicationsbecausethey areexecuted and drawn inlinewith aW eb 
page. Applets can more easily provide easy access to the graphics, user interface, and events 
systems in the W eb browser itself. T oday, you learned the basics of creating applets, including 
the following things: 


All applets you develop using J ava inherit from the appiet Class, part of the java.applet 
package. T he Applet Class provides basic behavior for how the applet will be integrated 
with and react to the browser and various forms of input from that browser and the 
person running it. By subclassing Appiet, you have access to all that behavior. 


Applets have five main methods, which are used for the basic activities an applet 
performs during its life cycle: init(), start(), stop(), destroy(), and paint(). 
Although you don’t need to override all these methods, these are the most common 
methods you'll see repeated in many of the applets you'll create in this book and in 
other sample programs. 


Torun acompiled applet class file, you include it in an HTML Web page by using 
the <appLeT> tag. When aJ ava-capable browser comes across <appLet>, it loads and 
plays the applet described in that tag. N ote that to publish J ava applets on the W orld 
W ide W eb alongside H TM L files you do not need special server software; any plain 
old W eb server will do just fine 


Unlike applications, applets do not have a common line on which to pass arguments, 
so those arguments must be passed into the applet through the HT ML file that 
contains it. You indicate parameters in an HTM L file by using the <param> tag inside 
the opening and closing <aPPLeT> tags. <PARAm> has two attributes: name for the name 
of the parameter, and va.ue for its value. Inside the body of your applet (usually in 
init()), you can then gain access to those parameters using the getParameter method. 


Q&A 


Q In the first part of today’s lesson, you say that applets are downloaded from 


random Web servers and run on the client’s system. What's to stop an applet 
developer from creating an applet that deletes all the files on that system, or in 
some other way compromises the security of the system? 


Recall that Java applets have several restrictions that make it difficult for most of the 
more obvious malicious behavior to take place. For example, because J ava applets 
cannot read or write files on the client system, they cannot delete files or read system 
files that might contain private information. Because they cannot run programs on the 
client’s system, they cannot, for example, use the system’s mail system to mail files to 
someone elsewhere on the network. 

In addition, J ava’s very architecture makes it difficult to circumvent these restrictions. 
T he language itself, the} ava compiler, and theJ ava interpreter all have checks to make 
sure that no one has tried to sneak in bogus code or play games with the system itself. 
You'll learn more about these checks at the end of this book. 


Of course, no system can claim to be entirely secure, and the fact that J ava applets are 
run on the client’s system makes them especially ripe for suspicion. 

Wait a minute. If | can’t read or write files or run programs on the system the 
applet is running on, doesn’t that mean | basically can’t do anything other than 
simple animations and flashy graphics? H ow can | save state in an applet? H ow 
can I create, say, a word processor or a spreadsheet as a J ava applet? 

For everyone who doesn’t believe that J ava is secure enough, there is someone who 
believes that J ava’s security restrictions are too severe for just these reasons. Yes, J ava 
applets are limited because of the security restrictions. But given the possibility for 
abuse, | believe that it’s better to err on the side of being more conservative as far as 
security is concerned. Consider it a challenge. 

Keep in mind, also, that J ava applications have none of the restrictions that J ava 
applets do, but because they are also compiled to bytecode, they are portable across 
platforms. It may be that the thing you want to create would make a much better 
application than an applet. 

| have an older version of H otJava. | followed all the examples in this section, 
but H otJ ava cannot read my applets (it seems to ignore that they exist). What's 
going on? 
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A You most likely have an alpha version of H ot) ava. Recall that significant changes were 


made to the] ava API and how Java applets are written between alpha and beta. The 
results of these changes are that browsers that support alpha applets cannot read beta 
applets, and vice versa. The HT ML tags are even different, so an older browser just 
Skips over newer applets, and vice versa. 

By the time you read this, there may bea new version of H ot ava with support for 
beta. If not, you can use N etscape 2.0 or the}D K's applet viewer to view applets 
written to the beta specification. 

| noticed in a page about the <app.et> tag that there's also a name attribute. You 
didn’t discuss it here. 

name iS used when you have multiple applets on a page that need to communicate with 
each other. You'll learn about this on D ay 12. 


| have an applet that takes parameters and an HTML file that passes it those 
parameters. But when my applet runs, all | get are null values. W hat’s going on 
here? 

Do the names of your parameters (in the name attribute) match exactly with the names 
you're testing for in getParameter? T hey must be exact, including case, for the match 
to be made M ake sure also that your <param> tags are inside the opening and closing 
<APPLET> tags, and that you haven’t misspelled anything. 
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N ow you havea basic understanding of how appletswork. For theremainder of thisweek you'll 
cover the sorts of things you can do with applets with the built-in J ava class libraries, and how 
you can combinethen to produceinteresting effects. You'll start today with how to draw to the 
screen— that is, how to produce lines and shapes with the built-in graphics primitive, how to 
print text using fonts, and how to use and modify color in your applets. T oday you'll learn, 
specifically: 


“| How the graphics system works in J ava: the Graphics Class, the coordinate system used 
to draw to the screen, and how applets paint and repaint 

(7 Using the] ava graphics primitives, including drawing and filling lines, rectangles, 
ovals, and arcs 

“ Creating and using fonts, including how to draw characters and strings and how to 
find out the metrics of a given font for better layout 


() All about color in Java, including the coior class and how to set the foreground 
(drawing) and background color for your applet 


Note: T oday’s lesson discusses many of the basic operations available to you with 
the J ava class libraries regarding graphics, fonts, and color. H owever, today’s lesson, 
as well as all of this book, is also intended to be more of an introduction and an 
overview than an exhaustive description of all the features available to you. Be sure 
to check out the Java API documentation for more information on the classes 
described today. 


T he Graphics Class 


W ith J ava’sgraphics capabilities, you can draw lines, shapes, characters, and imagesto thescreen 
insideyour applet. M ost of the graphics operationsin J avaare methods defined in thecraphics 
class. You don’t haveto createan instanceof Graphics in order to draw somethingin your applet; 
in your applet’s paint) method (which you learned about yesterday), you aregiven aGraphics 
object. By drawing on that object, you draw onto your applet and the results appear on screen. 


T hecraphics Classispart of thejava.awt package, so if your applet doesany painting (asit usually 
will), make sure you import that class at the beginning of your J ava file: 


import java.awt.Graphics; 


public class MyClass extended java.applet.Applet { 


} 


T he Graphics Coordinate System 


To draw an object on the screen, you call oneof thedrawing methods availablein thearaphics 
class. All the drawing methods have arguments representing endpoints, corners, or starting 
locations of the object as values in the applet’s coordinate system— for example, aline starts at 
the points 10,10 and ends at the points 20, 20. 


Java's coordinate system has the origin (a, 0) in the top left corner. Positive x values are to the 
right, and positivey valuesaredown. All pixel valuesareintegers; thereareno partial or fractional 
pixels. Figure 9.1 shows how you might draw a simple square by using this coordinate system. 


Figure 9.1. 0,0 
The] ava graphics coordi- 
nate sytem. 


+X 


20,20 


60,60 


+Y 


Java's coordinate system is different from many painting and layout programs that have their 
x and y in thebottom left. If you’renot used to working with this upside-down graphics system, 
it may take some practice to get familiar with it. 


Drawing and Filling 


The Graphics class provides a set of simple built-in graphics primitives for drawing, including 
lines, rectangles, polygons, ovals, and arcs. 


Note: Bitmap images, such as GIF files, can also be drawn by using the Graphics 
class. You'll learn about this tomorrow. 
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Lines 


To draw straight lines, use the drawLine method. drawLine takes four arguments: the x and y 
coordinates of the starting point and the x and y coordinates of the ending point. 


public void paint(Graphics g) { 
g.drawLine(25,25,75,75) ; 


Figure 9.2 shows the result of this snippet of code. 


Figure 9.2. 
Drawing lines 


Rectangles 
T he] ava graphics primitives provide not just one, but three kinds of rectangles: 


“| Plain rectangles 
_| Rounded rectangles, which are rectangles with rounded corners 
“| Three-dimensional rectangles, which are drawn with a shaded border 


For each of theserectangles, you havetwo methodsto choosefrom: onethat drawstherectangle 
in outline form, and one that draws the rectangle filled with color. 


To draw a plain rectangle, use either the drawrect OF fillRect methods. Both take four 
arguments: the x and y coordinates of the top left corner of the rectangle, and the width and 
height of the rectangle to draw. For example, thefollowing paint () method drawstwo squares: 
the left one is an outline and the right one is filled (Figure 9.3 snows the result): 
public void paint(Graphics g) { 

g.drawRect (20,20,60,60) ; 

g.fillRect(120,20,60,60) ; 
} 
Rounded rectanglesare, asyou might expect, rectangleswith rounded edges. T hedrawRoundRect 
and fil1lRoundRect methodsto draw rounded rectangles are similar to regular rectangles except 
that rounded rectangles have two extra arguments for the width and height of the angle of the 
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corners. T hosetwo arguments determine how far along the edges of the rectanglethearc for the 
corner will start; the first for the angle along the horizontal plane, the second for the vertical. 
Larger values for the angle width and height make the overall rectangle more rounded; values 
equal to the width and height of the rectangle itself produce a circle Figure 9.4 shows some 


examples of rounded corners. 


Figure 9.3. 
Rectangles 


Figure 9.4. 


Rounded corners TC 


20 


20 


H ere’s a paint method that draws two rounded rectangles: one as an outline with a rounded 
corner 1@ pixelssquare theother, filled, with arounded corner 20 pixelssquare(Figure9.5 shows 
the resulting squares): 

public void paint(Graphics g) { 


g.drawRoundRect (20,20,60,60,10,10); 
g.fi11RoundRect (120,20,60,60,20,20); 
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Figure 9.5. 
Rounded rectangles 


Finally, there are three-dimensional rectangles. T hese rectangles aren’t really 3D ; instead, they 
have a shadow effect that makes them appear either raised or indented from the surface of the 
applet. T hree-dimensional rectangles have four arguments for the x and y of the start position 
and the width and height of the rectangle The fifth argument isa boolean indicating whether 
the 3D effect is to raise the rectangle (true) or indent it (false). As with the other rectangles, 
therearealso different methodsfor drawing and filling: drawspRect and fil13DRect. H ere’Scode 
to producetwo of then— theleft oneindented, theright oneraised (Figure9.6 showstheresult): 
public void paint(Graphics g) { 

g.draw3DRect (20,20,60,60, true) ; 

g.draw3DRect(120,20,60,60,false) ; 
} 


Figure 9.6. 
Three-dimensonal 
rectangles 


Note: In the current beta version of the] ava developer's kit, it is very difficult to 
see the 3D effect on 3D rectangles, due to a very small line width. (In fact, | 
enhanced Figure 9.6 to better show the effect.) If you are having troubles with 3D 
rectangles, this may be why. Drawing 3D rectanglesin any color other than black 
makes them easier to see. 


Polygons 


Polygons are shapes with an unlimited number of sides. T o draw a polygon, you need a set of 
x and y coordinates, and the drawing method then starts at one, drawsalineto thesecond, then 
alineto the third, and so on. 


Aswith rectangles, you can draw an outlineor afilled polygon (thedrawPolygonand fillPolygon 
methods, respectively). You also have a choice of how you want to indicate the list of 
coordinates— either as arrays of x and y coordinates or as an instance of the Polygon class. 


Using the first method, the drawPolygon and fi11Polygon methods take three arguments: 


An array of integers representing x coordinates 
An array of integers representing y coordinates 
An integer for the total number of points 


Thex and y arrays should, of course, have the same number of elements. 


H ere’s an example of drawing a polygon’s outline by using this method (Figure 9.7 shows the 
result): 
public void paint(Graphics g) { 

int exes[] = { 39,94,97,142,53,58,26 }; 


int whys[] = { 33,74,36,70,108,80,106 }; 
int pts = exes.length; 


g.drawPolygon(exes,whys, pts) ; 
} 


Figure 9.7. 
A polygon. 


N otethat J avadoesnot automatically closethe polygon; if you want to completethe shape, you 
haveto includethestarting point of thepolygon at theend of thearray. D rawingafilled polygon, 
however, joins the starting and ending points. 
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T hesecond way of calling drawPolygon and #111Polygon isto usea Polygon object. The Polygon 
Classis useful if you intend to add pointsto the polygon or if you're building the polygon on the 
fly. The Polygon class enables you to treat the polygon as an object rather than having to deal 
with individual arrays. 


To create a polygon object you can either create an empty polygon: 
Polygon poly = new Polygon(); 


or create a polygon from a set of points using integer arrays, asin the previous example: 


int exes[] = { 39,94,97,142,53,58,26 }; 
int whys[] = { 33,74,36,70,108,80,106 }; 
int pts = exes.length; 

Polygon poly = new Polygon(exes,whys, pts) ; 


Once you havea polygon object, you can append points to the polygon as you need to: 
poly.addPoint (20,35) ; 


Then, to draw the polygon, just use the polygon object as an argument to drawPolygon or 
fil1Polygon. H ere’sthat previousexample, rewritten thistimewith apolygon object. You'll also 
fill this polygon rather than just drawing its outline (Figure 9.8 shows the output): 
public void paint(Graphics g) { 

int exes[] = { 39,94,97,142,53,58,26 }; 

int whys[] = { 33,74,36,70,108,80,106 }; 

int pts = exes.length; 

Polygon poly = new Polygon(exes,whys, pts) ; 

g.fi11Polygon(poly) ; 


Figure 9.8. 
Another polygon. 


Ovals 


U se ovals to draw ellipses or circles. O vals are just like rectangles with overly rounded corners. 
In fact, you draw them using the same four arguments: the x and y of the top corner, and the 


156 


width and height of the oval itself. N otethat, because you’redrawing an oval, thestarting point 
issome distance to the left and up from the actual outline of the oval itself. Again, if you think 
of it as a rectangle it’s easier to place. 


Aswith theother drawing operations, thedrawoval method drawsan outlineof an oval, andthe 
filloval method draws a filled oval. 


H ere’s an example of two ovals, a circle and an ellipse (Figure 9.9 shows how these two ovals 
appear on screen): 


public void paint(Graphics g) { 
g.drawO0val(20,20,60,60) ; 
g.fi110val(120,20,100,60) ; 
} 


Figure 9.9. 
Ovals 


Arc 


Of the drawing operations, arcs are the most complex to construct, which is why | saved them 
for last. An arc is a part of a oval; in fact, the easiest way to think of an arc is as a section of a 
complete oval. Figure 9.10 shows some arcs. 


Figure 9.10. 
Arcs 
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The drawArc method takes six arguments: the starting corner, the width and height, the angle 
at which to start thearc, and thedegreesto draw it beforestopping. O nceagain, thereiSadrawarc 
method to draw thearc’s outline and the ti114rc to fill the arc. Filled arcs are drawn as if they 
were sections of a pie instead of joining the two endpoints, both endpoints are joined to the 
center of the circle. 


Theimportant thing to understand about arcs is that you’re actually formulating the arc as an 
oval and then drawing only some of that. T he starting corner and width and height arenot the 
starting point and width and height of the actual arc as drawn on the screen; they're the width 
and height of the full ellipse of which the arc isa part. T hosefirst points determine the size and 
shape of the arc; the last two arguments (for the degrees) determine the starting and ending 
points. 


Let’s start with a simple arc, aC shape on a circle as shown in Figure 9.11. 


Figure 9.11. 
AC arc 


T oconstruct themethod to draw thisarc, thefirst thing you do isthink of it asacompletecircle 
Then you find thex and y coordinates and the width and height of that circle. T hosefour values 
are the first four arguments to the drawArc or fi11Arc Methods. Figure 9.12 shows how to get 
those values from the arc. 


Figure 9.12. <m—— 100 ———> 


Constructing a circular arc. 
100 


To get the last two arguments, think in degrees around the circle. Zero degreesis at 3 o'clock, 
90 degreesisat 12 o'clock, 180 at 9 o'clock, and 270 at 6 o'clock. T hestart of thearc isthedegree 
value of the start of thearc. In this example, the starting point isthetop of theC at 90 degrees; 
90 isthe fifth argument. 


T hesixth and last argument isanother degree valueindicating how far around thecircleto sweep 
and the direction to go in (it’s not the ending degree angle, as you might think). In this case, 
because you’re going halfway around the circle, you're sweeping 180 degrees— and 180 is 
therefore the last argument in the arc. Theimportant part is that you're sweeping 180 degrees 
counterclockwise, which isin the positive direction in Java. If you are drawing abackwardsC, 
you sweep 180 degreesin thenegative direction, and the last argument is-180. SeeFigure9.13 
for the final illustration of how this works. 


Note: It doesn’t matter which side of the arc you start with; because the shape of 
the arc has already been determined by the complete oval it’s a section of, starting 
at either endpoint will work. 


Figure 9.13. 90° 
Arcson circles 


180° o° 


180° 


270° 


H ere’s the code for this example you’ll draw an outline of theC and afilled C to its right, as 
shown in Figure 9.14: 
public void paint(Graphics g) { 

g.drawArc(20,20,60,60,90,180) ; 

g.f1i11Arc(120,20,60,60,90,180) ; 
} 
Circlesarean easy way to visualizearcson circles; arcson ellipses areslightly moredifficult. Let’s 
go through this same process to draw the arc shown in Figure 9.15. 
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Figure 9.14. 
Two circular arcs. 


Figure 9.15. 
An dliptical arc. 


Likethearc on thecircle, this arc isa piece of acomplete oval, in thiscase, an elliptical oval. By 
completing the oval that this arc isa part of, you can get the starting points and the width and 
height arguments for the drawArc Or fillArc Method (Figure 9.16). 


Figure 9.16. <—!|_— 140 ———> 
Arcson alipses A 


Then, all you need is to figure out the starting angle and the angle to sweep. T his arc doesn’t 
start on anice boundary such as 90 or 180 degrees, so you'll need sometrial and error. T hisarc 
starts somewhere around 25 degrees, and then sweeps clockwise about 130 degrees (Figure 


9.17). 
Figure 9.17. 90° 
Starting and ending points 
25° 
180° 0° 
re Mar 


270° 
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With all portions of the arc in place, you can write the code H ere’s the J ava code for this arc, 
both drawn and filled (notein thefilled casehow filled arcsaredrawn asif they werepiesections): 
public void paint(Graphics g) { 


g.drawArc(10,20,150,50,25, -130); 
g.fi11Arc(10,80,150,50,25, -130) ; 


} 
Figure 9.18 shows the two elliptical arcs. 


Figure 9.18. 
T wo elliptical arcs 


a. 
yg 


To summarize, here are the steps to take to construct arcs in J ava: 


Think of the arc as a slice of a complete oval. 


Construct the full oval with the starting point and the width and height (it often helps 
to draw the full oval on the screen to get an idea of the right positioning). 
Determine the starting angle for the beginning of the arc. 


D etermine how far to sweep the arc and in which direction (counterclockwise 
indicates positive values, clockwise indicates negatives). 


A Simple Graphics Example 


H ere’s an example of an applet that uses many of the built-in graphics primitives to draw a 
rudimentary shape. In this case, it’s alamp with aspotted shade (or a sort of cubist mushroom, 
depending on your point of view). Listing 9.1 hasthecomplete code for thelamp; Figure 9.19 
shows the resulting applet. 
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Figure 9.19. 
TheLamp applet. 


Type Listing 9.1. The Lamp class. 


import java.awt.*; 


: public class Lamp extends java.applet.Applet { 


13 

2 

3 

4: 

5: public void paint(Graphics g) { 
6 // the lamp platform 

7 g.fillRect (0,250,290, 290) ; 

8 

// the base of the lamp 
g.drawLine(125,250,125,160) ; 
g.drawLine(175,250,175,160) ; 


// the lamp shade, top and bottom edges 
g-.drawArc(85,157,130,50, -65,312) ; 
g.drawArc(85,87,130,50,62,58) ; 


// lamp shade, sides 
g.drawLine(85,177,119,89); 
g.drawLine(215,177,181,89); 


en ee ee ee ee ee ee ee ee 9 
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21: // dots on the shade 
22: g.fillArc(78,120,40,40,63, -174); 
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23: g.f1110val(120,96,40,40) ; 
24: g.fillArc(173,100,40,40,110,180) ; 


Copying and Clearing 


O nce you’ve drawn afew thingson thescreen, you may want to movethen around or clear the 
entire applet. The Graphics class provides methods for doing both these things. 


The copyArea method copies a rectangular area of the screen to another area of the screen. 
copyArea takes six arguments: the x and y of the top corner of the rectangle to copy, the width 
and the height of that rectangle, and the distancein thex and y directions to which to copy it. 
For example, this line copies a square area 100 pixels on aside 100 pixels directly to its right: 


g.copyArea(@,0,100,100,100,0) ; 


To clear a rectangular area, use the clearRect method. clearrect, which takes the same four 
arguments as the drawRect and fillrect methods, fills the given rectangle with the current 
background color of the applet (you'll learn how to set the current background color later on 
today). 


To clear the entire applet, you can use the size() method, which returns a Dimension object 
representing the width and height of the applet. You can then get to theactual values for width 
and height by using the width and height instance variables: 


g.clearRect(0,0,this.size().width,this.height()); 


Text and Fonts 


T heGraphics Classalso enablesyou to print text on thescreen, in conjunction with theFont class, 
and, sometimes, the Front metrics Class. The Font class represents a given font— itsname, style, 
and point size— and Font metrics givesyou information about that font (for example, theactual 
height or width of a given character) so that you can precisely lay out text in your applet. 


N ote that thetext hereis static text, drawn to the screen onceand intended to stay there. You'll 
learn about entering text from the keyboard later on this week. 


Creating Font Objects 


To draw text to the screen, first you need to create an instance of the Font class. Font objects 
represent an individual font— that is, its name, style (bold, italic), and point size Font names 
are strings representing the family of the font, for example, "TimesRoman", "Courier", OF 
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"Helvetica". Font stylesare constants defined by the Font class; you can get to them using class 
variables— for example, Font. PLAIN, Font .BOLD, OF Font. ITALIC. Finally, thepoint sizeisthesize 
of the font, as defined by the font itself; the point size may or may not be the haght of the 
characters. 


T ocreatean individual font object, usethesethreeargumentsto theront class’snew constructor: 
Font f = new Font("TimesRoman", Font.BOLD, 24); 


T hisexamplecreatesa font object for theTimesRoman BoLp font, in 24 points. N otethat likemost 
Java classes, you have to import this class before you can useit. 


Font styles are actually integer constants that can be added to create combined styles; for 
example, Font.BOLD + Font. ITALIc produces a font that is both bold and italic. 


The fonts you have available to you in your applet depend on the system on which the applet 
is running. Currently, although there is a mechanism in Java to get a list of fonts (see the 
getFontList method, defined in the java.awt.Toolkit Class), it appears not to be working 
currently in the beta version of the] D K. O nce these capabilities work, it is possibleto get alist 
of fonts on the system and to be able to make choices based on that list; for now, to make sure 
your applet is completely compatible across systems, it’s a very good idea to limit the fonts you 
usein your applets to "TimesRoman", "Helvetica", and "Courier". If Javacan’t find afont you 
want to use, it will substitute some default font, usually C ourier. 


Drawing Characters and Strings 


With afont object in hand, you can draw text on the screen using the methodsdrawchars and 
drawString. First, though, you need to set the current font to your font object using thesetFont 
method. 


T hecurrent font ispart of thegraphicsstatethat iskept track of by thecraphics object on which 
you’re drawing. Each time you draw a character or a string to the screen, that text is drawn by 
using the current font. To change the font of the text, first change the current font. Here's a 
paint () method that creates a new font, sets the current font to that font, and drawsthestring 
"This is a big font.", Starting from the point 10, 100. 
public void paint(Graphics g) { 

Font f = new Font("TimesRoman", Font.PLAIN, 72) ; 

g.setFont(f); 

g.drawString("This is a big font.",10,100); 
} 
This should all look familiar to you; this is how the H ello applets throughout this book were 
produced. 


Thelatter two arguments to drawstring determine the point where the string will start. T hex 
value is the start of the leftmost edge of the text; y is the baseline for the entire string. 


Similar to drawstring isthe drawchars method that, instead of taking a string as an argument, 
takes an array of characters. drawCchars has five arguments: the array of characters, an n integer 
representing the first character in the array to draw, another integer for the last character in the 
array to draw (all characters between the first and last aredrawn), and thex and y for thestarting 
point. M ost of the time, drawstring is more useful than drawchars. 


Listing 9.2 shows an applet that draws several lines of text in different fonts; Figure 9.20 shows 
the result. 


Type Listing 9.2. Many different fonts. 


1: import java.awt.Font; 
2: import java.awt.Graphics; 


: public class ManyFonts extends java.applet.Applet { 


4 
5 
6 public void paint(Graphics g) { 

Ti Font f = new Font("TimesRoman", Font.PLAIN, 18); 
8 Font fb new Font("TimesRoman", Font.BOLD, 18); 
9 

10 


: Font fi new Font("TimesRoman", Font.ITALIC, 18); 
7 Font fbi = new Font("TimesRoman", Font.BOLD + Font.ITALIC, 18); 
11: 
12: g.setFont (Ff) ; 
13: g.drawString("This is a plain font", 10, 25); 
14: g.setFont (fb) ; 
15: g.drawString("This is a bold font", 10, 50); 
16: g.setFont (fi); 
17: g.drawString("This is an italic font", 10, 75); 
18: g.setFont (fbi) ; 
19: g.drawString("This is a bold italic font", 10, 100); 
20: } 
21: 
22: } 
Figure 9.20. 
Teeubane This is a plain font 
M anyF onts applet. 


This is a bold font 
This is am tfalie fomt 
this is a bold italic font 
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Finding Out Information About a Font 


Sometimes, you may want to makedecisionsin your J ava program based on the qualities of the 
current font— for example, its point size, or the total height of its characters. You can find out 
some basic information about fonts and font objects by using simple methods on Graphics and 
on the Font objects. T able 9.1 shows some of these methods: 


Table 9.1. Font methods. 
Method Name InObject Action 


getFont() Graphics Returns the current font object as previously set by 
setFont() 

getName ( ) Font Returns the name of the font asa string 

getSize() Font Returns the current font size (an integer) 

getStyle() Font Returns the current style of the font (styles are integer 
constants: @ is plain, 1 is bold, 2 isitalic, 3 is bold italic) 

isPlain() Font Returns true OF false if the font’s styleis plain 

isBold() Font Returns true Or false if the font’s style is bold 

isItalic() Font Returns true OF false if the font’s style is italic 


For more detailed information about the qualities of the current font (for example, the length 
or height of given characters), you need to work with font metrics. The Fontmetrics Class 
describes information specific to a given font: the leading between lines, the height and width 
of each character, and so on. T o work with thesesorts of values, you create aFontmetrics object 
based on the current font by using the applet method getFontMetrics: 


Font f = new Font("TimesRoman", Font.BOLD, 36); 
FontMetrics fmetrics = getFontMetrics(f); 
g.setfont (Ff); 


T able9.2 showssomeof thethingsyou can find out usingfont metrics. All thesemethodsshould 
be called on a Fontmetrics object. 


Table 9.2. Font metrics methods. 
Method Name Action 
stringWidth() Given astring, returns the full width of that string, in pixels 
charWidth() Given acharacter, returns the width of that character 
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Method Name __ Action 

getAscent() Returns the ascent of the font, that is, the distance between the 
font’s baseline and the top of the characters 

getDescent() Returns the descent of the font— that is, the distance between the 
font’s baseline and the bottoms of the characters (for characters such 
as p and q that drop below the baseline) 

getLeading() Returns the leading for the font, that is, the spacing betweenthe 
descent of one line and the ascent of another line 

getHeight () Returns the total height of the font, which is the sum of the ascent, 
descent, and leading value 


Asan example of thesorts of information you can use with font metrics, Listing 9.3 snhowsthe 
Java code for an applet that automatically centers a string horizontally and vertically inside an 
applet. T he centering position is different depending on the font and font size; by using font 
metrics to find out the actual size of a string, you can draw thestring in the appropriate place. 


N otethe applet.size() method here, which returns the width and height of the overall applet 
areaaSaDimension object. You can then get to theindividual width and height byusingthewidth 
and height instance variables. 


Figure 9.21 shows the result (less interesting than if you actually compile and experiment with 
various applet sizes). 


| | 
Type Listing 9.3. Centering a string. 


1: import java.awt.Font; 

2: import java.awt.Graphics; 

3: import java.awt.FontMetrics; 

4: 

5: public class Centered extends java.applet.Applet { 

6: 

7: public void paint(Graphics g) { 

8: Font f = new Font("TimesRoman", Font.PLAIN, 36); 

9: FontMetrics fm = getFontMetrics(f) ; 

10: g.setFont(f) ; 

11: 

12: String s = "This is how the world ends."; 

13: int xstart = (this.size().width - fm.stringWidth(s)) / 2; 
14: int ystart = (this.size().height - fm.getHeight()) / 2; 
15: 

16: g.drawString(s, xstart, ystart); 

17: 

18:} 
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Figure 9.21. — 
The centered text. This is how the world ends. 


Color 


D rawing black linesand testson agray background isall very nice, but being ableto usedifferent 
colors is much nicer. J ava provides methods and behaviors for dealing with color in general 
through the color class, and also provides methods for setting the current foreground and 
background colors so that you can draw with the colors you created. 


Java's abstract color model uses 24-bit color, wherein acolor isrepresented asa combination of 
red, green, and bluevalues. Each component of thecolor can haveanumber between a and 255. 
@,0,0iSblack, 255,255,255 is white, and J avacan represent millions of colors between as well. 


Java's abstract color model mapsonto thecolor modd of theplatform J avaisrunningon, which 
usually has only 256 colors or fewer from which to choose. I f arequested color in acolor object 
isnot availablefor display, theresulting color may bemapped to another or dithered, depending 
on how thebrowser viewing thecolor implemented it, and depending on theplatform on which 
you're running. In other words, although Java gives the capability of managing millions of 
colors, very few may actually be available to you in real life. 


Using Color Objects 


T odraw an object in aparticular color, you must createan instanceof theco1or classto represent 
that color. The color class defines a set of standard color objects, stored in class variables, that 
enable you quickly to get a color object for some of the more popular colors. For example, 
Color.red QiVeSYOU acolor object representing red (RGB valuesof 255, a, and @), color.white 
gives you a white color (RGB values of 255, 255, and 255), and so on. Table 9.3 shows the 
standard colors defined by variables in the color class. 


Table 9.3. Standard colors. 


Color Name RGB Value 
Color.white 255,255,255 
Color.black 0,0,0 


Color.lightGray 192,192,192 
Color.gray 128,128,128 
Color.darkGray 64,64,64 
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Color Name RGB Value 
Color.red 255,0,0 
Color.green 0,255,0 
Color.blue 0,0,255 
Color.yellow 255,255,0 
Color.magenta 255,0,255 
Color.cyan 0,255,255 
Color.pink 255,175,175 
Color.orange 255 ,200,0 


If the color you want to draw in isnot oneof the standard color objects, fear not. You can create 
acolor object for any combination of red, green, and blue, aslong as you have the values of the 
color you want. J ust create a new color object: 


Color c = new Color(140,140,140); 


This line of Java code creates a color object representing a dark grey. You can use any 
combination of red, green, and blue values to construct a color object. 


Alternatively, you can also create a color object using three floats from 0. to 1.0: 


Color c = new Color(0.34,1.0,0.25) 


Testing and Setting the Current Colors 


T o draw an object or text using acolor object, you haveto set the current color to be that color 
object, just as you haveto set the current font to the font in which you want to draw. U sethe 
setColor method (a method for Graphics objects) to do this: 


g.setColor(Color.green) ; 
After setting the current color, all drawing operations will occur in that color. 


In addition to setting thecurrent color for thegraphics context, you can also set the background 
and foreground colors for the applet itself by using the setBackground and setForeground 
methods. Both of these methods are defined in the java. awt. Component Class, which Applet— 
and therefore your classes— automatically inherits. 


T hésetBackground method setsthebackground color of theapplet, which isusually adark grey. 
It takes a single argument, a color object: 


setBackground(Color.white) ; 
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T hesetForeground method also takesa single color asan argument, and affects everything that 
has been drawn on the applet, regardless of the color in which it has been drawn. You can use 
setForeground to change the color of everything in the applet at once, rather than having to 
redraw everything: 


setForeground(Color.black) ; 


In addition to thesetcolor, setForeground, and setBackground methods, therearecorrespond- 
ing “get” methods that enable you to retrieve the current graphics color, background, or 
foreground. T hosemethodsaregetcolor (defined in Graphics objects), getForeground (defined 
iN Applet), ANd getBackground (alSO iN Applet). YOu can use these methods to choose colors 
based on existing colors in the applet: 


setForeground(g.getColor()); 


A Single Color Example 


Listing 9.4 shows the code for an applet that fills the applet’s drawing area with square boxes, 
each of which hasarandomly chosen color init. It’swritten so thatit can handleany sizeof applet 
and automatically fill the area with the right number of boxes. 


Type Listing 9.4. Random color boxes. 


1: import java.awt.Graphics; 

2: import java.awt.Color; 

3: 

4: public class ColorBoxes extends java.applet.Applet { 

5: 

6: public void paint(Graphics g) { 

Ti int rval, gval, bval; 

8: 

9: for (int j = 30; j < (this.size().height -25); j += 30) 
10: for (int i = 5; i < (this.size().width -25); it= 30) { 
11: rval = (int)Math.floor(Math.random() * 256); 
12: gval = (int)Math.floor(Math.random() * 256); 
13: bval = (int)Math.floor(Math.random() * 256); 
14: 

15: g.setColor(new Color(rval,gval,bval) ); 
16: g.fillRect(i,j,25,25); 

17: g.setColor(Color.black) ; 

18: g.drawRect(i-1,j-1,25,25); 

19: } 

20: } 

21: } 


Analyss T hetwo for loopsaretheheart of thisexample thefirst onedrawstherows, and thesecond 


draws the individual boxes within the row. When a box is drawn, the random color is 


calculated first, and then the box is drawn. A black outline is drawn around each box, because 
some of them tend to blend into the background of the applet. 


Because this paint method generates new colors each time the applet is painted, you can 
regenerate the colors by moving the window around or by covering the applet’s window with 
another one. Figure 9.22 shows the final applet (although given that this picture is black and 
white, you can’t get the full effect of the multicolored squares). 


Figure 9.22. 
Therandom colors apple. 
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Summary 


You present something on the screen by painting inside your applet: shapes, graphics, text, or 
images. T oday, you learned the basics of how to paint, including using the graphics primitives 
to draw rudimentary shapes, using fonts and font metrics to draw text, and usingcolor objects 
to change the color of what you're drawing on the screen. It’s this foundation in painting that 
enables you to do animation inside an applet (which basically involves just painting repeatedly 
to the screen) and to work with images. T hese are topics you'll learn about tomorrow. 


Q&A 


Q_ Inall the examples you show, and in all the tests I’ve made, the graphics primi- 
tives, such aS drawLine and drawkect, produce lines that are one pixel wide. H ow 
can I draw thicker lines? 

A In the current state of the) ava Graphics class, you can’t; no methods exist for chang- 
ing the default line width. If you really need a thicker line, you have to draw multiple 
lines one pixel apart to produce that effect. 

Q | wrote an applet to use H elvetica. It worked fine on my system, but when I run 
it on my friend’s system, everything is in Courier. Why? 
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A Your friend most likely doesn’t have the H elvetica font installed on his or her system. 
W hen J ava can’t find a font, it substitutes a default font instead— in your case, 
Courier. The best way to deal with this is to query the font list. As!’m writing this, 
however, querying the font list doesn’t yet work, so your safest bet is to stick with 
either Times Roman or Courier in your applets. 


Q | tried out that applet that draws boxes with random colors, but each time it 
draws, a lot of the boxes are the same color. If the colors are truly random, why is 
it doing this? 

A Two reasons. The first is that the random number generator | used in that code (from 
the math Class) isn’t a very good random number generator; in fact, the documentation 
for that method says as much. For a better random number generator, use the random 
class from the java.util package. 


The second, more likely, reason is that there just aren’t enough colors availablein your 
browser or on your system to draw all the colors that the applet is generating. If your 
system can’t produce the wide range of colors available using the color class, or if the 
browser has allocated too many colors for other things, you may end up with duplicate 
colors in the boxes, depending on how the browser and the system has been written to 
handle that. U sually your applet won’t use quite so many colors, so you won't run 

into this problem quite so often. 
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The first thing! ever saw J ava do wasan animation: alargered "Hi there!" that ran acrossthe 
screen from the right to left. Even that simple form of animation was enough to make me stop 
and think, “this is really cool.” 


T hat sort of simple animation takes only a few methods to implement in Java, but those few 
methods are the basis for any Java applet that you want to update the screen dynamically. 
Starting with simple animations is a good way to build up to the more complicated applets. 
T oday, you'll learn the fundamentals of animation in J ava: how the various parts of the systen 
all work together so that you can create moving figures and dynamic updateable applets. 
Specifically, you'll explore the following: 


“| How Javaanimations work— the paint) and repaint() methods, starting and 
stopping dynamic applets, and how to use and override these methods in your own 
applets 

"| Threads— what they are and how they can make your applets more well-behaved with 
other applets and with the J ava system in general 


(] Reducing animation flicker, acommon problem with animation in Java 


Throughout today, you'll also work with lots of examples of real applets that create animations 
or perform some kind of dynamic movement. 


Creating Animation in J ava 


Animation in J ava involves two steps: constructing a frame of animation, and then asking] ava 
to paint that frame. Repeat as necessary to create the illusion of movement. The basic, static 
applets that you created yesterday taught you how to accomplish the first part; all that’s left is 
how to tell Java to paint a frame 


Painting and Repainting 
The paint() method, as you learned yesterday, is called by J ava whenever the applet needs to 
be painted— when the applet is initially drawn, when the window containing it is moved, or 
when another window is moved from over it. You can also, however, ask Java to repaint the 
applet at atime you choose. So, to changethe appearanceof what ison thescreen, you construct 
the image or “frame” you want to paint, and then ask J ava to paint this frame. If you do this 
repeatedly, and fast enough, you get animation inside your J ava applet. T hat’s all thereisto it. 


W here does all this take place? N ot in the paint) method itself. All paint) doesis put dots 
on thescreen. paint(),in other words, isresponsibleonly for thecurrent frameof theanimation 
at a time. The real work of changing what paint() does, of modifying the frame for an 
animation, actually occurs somewhere else in the definition of your applet. 
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In that “somewhere else,” you construct the frame (set variables for paint) to use, create color 
or font or other objects that paint ) will need), and then call the repaint ) method. repaint () 
is the trigger that causes J ava to call paint() and causes your frame to get drawn. 


Technical Note: Because a J ava applet can contain many different components 
that all need to be painted (as you'll learn later on this week), and in fact, applets 
are enbedded inside a larger J ava application that also paints to the screen in 
similar ways, when you Call repaint() (and therefore paint ()) you're not actually 
immediately drawing to the screen as you do in other window or graphics toolkits. 
Instead, repaint() isarequet for Java to repaint your applet as soon asit can. 

M uch of the time, the delay between the call and the actual repaint is negligible. 


Starting and Stopping 
an Applet’s E xecution 


Remember start() and stop() from D ay 8?T hese are the methods that trigger your applet to 
start and stop running. You didn’t us@start() and stop() yesterday, because theappletson that 
day did nothing except paint once. With animations and other J ava applets that are actually 
processing and running over time, you'll need to make use of start() and stop) to trigger the 
start of your applet’s execution, and to stop it from running when you leave the page that 
containsthat applet. For most applets, you'll wantto overridestart and stop for justthisreason. 


Thestart() method triggers the execution of the applet. You can either do all the applet’s work 
inside that method, or you can call other object’s methods in order to do so. U sually, start() 
is used to create and begin execution of athread so the applet can run in its own time. 


stop(), on the other hand, suspects an applet’s execution so when you move off the page on 
which the applet is displaying, it doesn’t keep running and using up system resources. M ost of 
the time when you create a start() method, you should also create a corresponding stop(). 


Putting It Together 


Explaining how to do Java animation in text is more of a task than actually showing you how 
it worksin code. An example or two will help makethe relationship between all these methods 
Clearer. 


Listing 10.1 shows a sample applet that, at first glance, uses basic applet animation to display 
thedateand timeand constantly updatesit every second, creating avery simpleanimated digital 
clock (a frame from that clock is shown in Figure 10.1). 
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The words “at first glance” in the previous paragraph are very important: this applet doesn’t 
work! H owever, despite the fact that it doesn’t work, you can still learn a lot about basic 
animation with it, so working through the code will still be valuable. |In the next section, you'll 
learn just what's wrong with it. 


See whether you can figure out what’s going on with this code before you go on to theanalysis. 


Type 


13 


Listing 10.1. The Date applet. 


import java.awt.Graphics; 


2 import java.awt.Font; 
3: import java.util.Date; 
4 
5: public class DigitalClock extends java.applet.Applet { 
6: 
7 Font theFont = new Font("TimesRoman",Font.BOLD, 24) ; 
8 Date theDate; 
9 
10 public void start() { 
11: while (true) { 
12: theDate = new Date(); 
13: repaint(); 
14: try { Thread.sleep(1000); } 
15: catch (InterruptedException e) { } 
16: x, 
17: } 
18: 
19: public void paint(Graphics g) { 
20: g.setFont(theFont) ; 
21: g.drawString(theDate.toString(),10,50); 
22: } 
23: } 
Figure 10.1. 


The digital clock. 


Analyss 


Sun Nov 05 20:43:02 PST 1995 


Think you've got the basic idea? Let’s go through it, line by line 


Lines 7 and 8 define two basic instance variables: theFont and theDate, which hold objects 
representing the current font and the current date, respectively. M ore about these later. 
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Thestart() method triggersthe actual execution of theapplet. N otethewnile loop insidethis 
method; given that the test (true) alwaysreturns true, theloop never exits. A singleanimation 
frame is constructed inside that while loop, with the following steps: 


T he pate class represents a date and time (Date is part of the java.util package— note 
that it was specifically imported in line three). Line 12 creates a new instance of the 
Date Class, which holds the current date and time, and assignsit to the theDate 
instance variable. 


The repaint () method is called. 


Lines 14 and 15, as complicated as they look, do nothing except pause for 1000 
milliseconds (one second) before the loop repeats. The sleep() method there, part of 
the Thread Class, is what causes the applet to pause Without a specific sieep() 
method, the applet would run as fast as it possibly could, which, for faster computer 
systems, might be too fast for the eye to see. Using sleep) enables you to control 
exactly how fast the animation takes place. The try and catch stuff around it enables 
Java to manage errors if they occur. try and catch are called exceptions and are 
described on D ay 18, next week. 


On to the paint() method. H eve, inside paint(), all that happens is that the current font (in 
the variable theFont) isset, and the date itself is printed to the screen (notethat you haveto call 
the tostring() method to convert thedateto astring). Becausepaint () iscalled repeatedly with 
whatever value happens to bein theDate, the string is updated every second to reflect the new 
date. 


T herearea few things to note about this example. First, you might think it would be easier to 
create the new pate object inside the paint() method. T hat way you could usea local variable 
and not need an instance variable to pass the pate object around. Although doing things that 
way creates cleaner code, it also resultsin aless efficient program. T he paint () method is called 
every time a frame needs to be changed. In this case, it’s not that important), but in an 
animation that needsto change frames very quickly, the paint () method has to pause to create 
that new object every time. By leaving paint() to do what it does best— painting the screen— 
and calculating new objects beforehand, you can make painting as efficient as possible. T hisis 
precisely the same reason why the Font object is also in an instance variable. 


Threads: What They Are 
and Why You Need Them 


Depending on your experience with operating systems and with environments within those 
systems, you may or may not haverun into theconcept of threads. Let’s start from thebeginning 
with some definitions. 


177 


® DAY @ 
Simple Animation and Threads 


178 


When a program runs, it starts executing, runs its initialization code, calls methods or 
procedures, and continues running and processing until it’s complete or until the program is 
exited. T hat program uses a single thread— where the thread is a single locus of control for the 
program. 


Multithreading, asin J ava, enables several different execution threads to run at the same time 
inside the same program, in parallel, without interfering with each other. 


H ere’s a simple example. Suppose you have along computation near the start of a program’s 
execution. This long computation may not be needed until later on in the program's 
execution— it’s actually tangential to the main point of the program, but it needs to get done 
eventually. In asingle threaded program, you haveto wait for that computation to finish before 
the rest of the program can continue running. In a multithreaded system, you can put that 
computation into its own thread, enabling the rest of the program to continue running 
independently. 


U singthreadsin J ava, you can createan applet so that it runsin itsown thread, and it will happily 
run all by itself without interfering with any other part of the system. U sing threads, you can 
have lots of applets running at once on the same page. D epending on how many you have, you 
may eventually exhaust the system so that all of them will run slower, but all of them will run 
independently. 


Even if you don’t have lots of applets, using threads in your appletsis good J ava programming 
practice. The general rule of thumb for well-behaved applets: whenever you have any bit of 
processing that is likely to continue for along time (such as an animation loop, or abit of code 
that takes along time to execute), put it in a thread. 


The Problem with the Digital Clock Applet 


T hat Digital C lock applet in the last section doesn’t usethreads. Instead, you put thewhi1e loop 
that cyclesthrough theanimation directly into thestart() method so that when theapplet starts 
running it keeps going until you quit the browser or applet viewer. Although this may seem like 
agood way to approach the problem, the digital clock won't work because thewnile loop in the 
start () Method ismonopolizing all theresourcesin the system— including painting. If you try 
compiling and running the digital clock applet, all you get isa blank screen. You also won't be 
able to stop the applet, because there’s no way a stop() method can ever be called. 


Thesolution to this problem is to rewrite the applet to use threads. T hreads enable this applet 
to animate on its own without interfering with other system operations, enable it to be started 
and stopped, and enable you to run it in parallel with other applets. 


Writing Applets with Threads 


H ow do you create an applet that uses threads? T here are several things you need to do. 
Fortunately, noneof them are difficult, and alot of the basics of using threadsin applets isjust 
boilerplate code that you can copy and paste from one applet to another. Because it’s so easy, 
there's almost no reason not to use threads in your applets, given the benefits. 


T here are four modifications you need to make to create an applet that uses threads: 


Change the signature of your applet class to include the words implements Runnable. 
Include an instance variable to hold this applet’s thread. 

M odify your start() method to do nothing but spawn a thread and start it running. 
Create a run() method that contains the actual code that starts your applet running. 


T hefirst changeisto thefirst lineof your classdefinition. You’vealready got something |likethis: 
public class MyAppletClass extends java.applet.Applet { 


} 


You need to changeit to the following (I’ve put it on two lines so it'll fit on this page; it can be 
either like this or on one line depending on your preference): 


public class MyAppletClass extends java.applet.Applet implements Runnable { 


} 


W hat does this do? It includes support for the Runnable interface in your applet. If you think 
way back to D ay 2, you'll remember that interfaces area way to collect method namescommon 
to different classes, which can then be mixed in and implemented inside different classes that 
need to implement that behavior. H ere, therunnable interfaceincludesthebehavior your applet 
needs to run athread; in particular, it gives you a default definition for the run() method. 


Thesecond step is to add an instance variable to hold this applet’s thread. Call it anything you 
like; it’s a variable of the type Thread (Thread iSaclassin java.1ang, SO you don’t haveto import 
it): 

Thread runner; 


Third, add astart() method or modify theexisting oneso that it does nothing but createanew 
thread and start it running. H ere’s atypical example of a start() method: 
public void start() { 
if (runner == null); { 
runner = new Thread(this) ; 
runner.start(); 
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If you modify start ) to do nothing but spawn a thread, where does the body of your applet 
go? It goes into anew method, runc), which looks like this: 
public void run() { 

// what your applet actually does 
} 
run() Can contain anything you want to run in theseparatethread: initialization code, theactual 
loop for your applet, or anything else that needs to run in its own thread. You also can create 
new objects and call methods from insiderun(), and they'll also run insidethat thread. Therun 
method is the real heart of your applet. 


Finally, now that you’vegot threads running and astart method to start them, you should add 
astop() method to suspend execution of that thread (and thereforewhatever theapplet isdoing 
at the time) when the reader leaves the page. stop(), like start(), is usually something along 
these lines: 
public void stop() { 

if (runner != null) { 


runner.stop(); 
runner = null; 


} 


The stop() method here does two things: it stops the thread from executing and also sets the 
thread’s variable (runner) to nui. Setting the variable to nui1 makes the Thread object it 
previously contained available for garbage collection so that the applet can be removed from 
memory after a certain amount of time. If the reader comes back to this page and this applet, 
the start method creates a new thread and starts up the applet once again. 


And that’sit! Four basic modifications, and now you have awell-behaved applet that runsin its 
own thread. 


Fixing The Digital Clock 


Remember theproblensyou had with theD igital Clock applet at the beginning of thissection? 
Let's fix them so you can get an idea of how areal applet with threads looks. You'll follow the 
four steps outlined in the previous section. 


First, modify the class definition to include the Runnable interface (the class is reamed to 
DigitalThreads instead Of DigitalClock): 


public class DigitalThreads extends java.applet.Applet 
implements Runnable { 


Second, add an instance variable for the threaa: 


Thread runner; 
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For the third step, swap the way you did things. Because the bulk of the applet is currently in 
a method called start(), but you want it to bein amethod called run(), rather than do alot 
of copying and pasting, just rename the existing start() to run(): 


public void run() { 
while (true) { 


Finally, add the boilerplate start() and stop) methods: 


public void start() { 
if (runner == null); { 
runner = new Thread(this) ; 
runner.start(); 


} 


public void stop() { 
if (runner != null) { 
runner.stop() 5 
runner = null; 


} 


You'refinished! O neapplet converted to usethreadsin lessthan aminuteflat. T hecodefor the 
final applet appears in Listing 10.2. 


=i 
4 
= 

(a>) 


Listing 10.2. The fixed digital clock applet. 


1: import java.awt.Graphics; 

2: import java.awt.Font; 

3: import java.util.Date; 

4: 

5: public class DigitalThreads extends java.applet.Applet 
6: implements Runnable { 

7: 

8: Font theFont = new Font("TimesRoman",Font.BOLD, 24) ; 
9: Date theDate; 

10: Thread runner; 

11: 

12: public void start() { 

13: if (runner == null); { 

14: runner = new Thread(this) ; 
15: runner.start(); 

16: } 

17: } 

18: 

19: public void stop() { 

20: if (runner != null) { 

21: runner.stop(); 

22: runner = null; 

23: } 

24: } 


continues 
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Listing 10.2. continued 


25: 

26: public void run() { 

27: while (true) { 

28: theDate = new Date(); 

29: repaint(); 

30: try { Thread.sleep(1000); } 

31: catch (InterruptedException e) { } 
32: } 

33: } 

34: 

35: public void paint(Graphics g) { 

36: g.setFont(theFont) ; 

37: g.drawString(theDate.toString(),10,50); 
38: } 

39: } 

40: 


R educing Animation F licker 


If you've been following along with this book and trying the examples as you go, rather than 
reading this book on the airplane or in the bathtub, you may have noticed that when the date 
program runs every once in a while, there's an annoying flicker in the animation. (N ot that 
there's anything wrong with reading this book in the bathtub, but you won't see the flicker if 
you do that, so just trust me— there's a flicker.) T hisisn’t a mistake or an error in the program; 
in fact, that flicker is a side effect of creating animationsin J ava. Because it is really annoying, 
however, you'll learn how to reduceflicker in this part of today’s lesson so that your animations 
run cleaner and look better on the screen. 


Flicker and How to Avoid It 


Flicker is caused by the way J ava paints and repaints each frame of an applet. At the beginning 
of today’slesson, you learned that when you call therepaint() method, repaint() CallSpaint(). 
T hat’s not precisely true. A call to paint() does indeed occur in response to arepaint(), but 
what actually happens are the following steps: 


1. Thecall to repaint) results in acall to the method upaate(). 


2. Theupdate() method clears the screen of any existing contents (in essence, fills it with 
the current background color), and then calls paint(). 


3. The paint() method then draws the contents of the current frame 
It’s Step 2, the call to update(), that causes animation flicker. Because the screen is cleared 


between frames, theparts of thescreen that don’t changealternaterapidly between being painted 
and being cleared. H ence, flickering. 
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There are two major ways to avoid flicker in your J ava applets: 


Override update) either not to clear the screen at all, or to clear only the parts of the 
screen you've changed. 


Override both update() and paint(), and use double buffering. 


If the second way sounds complicated, that’s becauseit is. D ouble buffering involves drawing 
to an offscreen graphics surface and then copying that entire surface to the screen. Because it’s 
more complicated, you'll explore that one tomorrow. T oday, let’s cover the easier solution: 
overriding update. 


H ow to Override U pdate 


T he cause of flickering liesin the update() method. To reduce flickering, therefore, override 
both update() and paint(). H ere’s what the default version of update) does (in the component 
class, which you'll learn more about on D ay 13): 


public void update(Graphics g) { 
g.setColor(getBackground() ) ; 
g.fillRect(®, @, width, height); 
g.setColor(getForeground() ); 
paint(g); 


Basically, update) Clears the screen (or, to be exact, fills the applet’s bounding rectangle with 
the background color), sets things back to normal, and then calls paint(). When you override 
update (), you haveto keep thesetwo thingsin mind and makesurethat your version of update ( ) 
does something similar. In the next two sections, you'll work through some examples of 
overriding update() in different cases to reduce flicker. 


Solution One: Don’t Clear the Screen 


Thefirst solution to reducing flicker is not to clear the screen at all. This works only for some 
applets, of course. H ere’s an example of an applet of thistype. The ColorSwirl applet prints a 
single string to the screen ("all the swirly colors"), but that string is presented in different 
colors that fadeinto each other dynamically. T his applet flickers terribly when it’s run. Listing 
10.3 shows the source for this applet, and Figure 10.2 shows the result. 


Type Listing 10.3. The ColorSwirl applet. 


1 import java.awt.Graphics; 
2: import java.awt.Color; 

3: import java.awt.Font; 
4: 


continues 
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Listing 10.3. continued 


5: public class ColorSwirl extends java.applet.Applet 
6: implements Runnable { 

7: 

8: Font f = new Font("TimesRoman",Font.BOLD, 48) ; 
9: Color colors[] = new Color[5Q]; 

10: Thread runThread; 

11: 

12: public void start() { 

13: if (runThread == null) { 

14: runThread = new Thread(this) ; 

15: runThread.start(); 

16: } 

17: } 

18: 

19: public void stop() { 

20: if (runThread != null) { 

21: runThread.stop() ; 

22: runThread = null; 

23: } 

24: } 

25: 

26: public void run() { 

27: 

28: // initialize the color array 

29: float c = Q; 

30: for (int i = 0; i < colors.length; it+) { 
31: colors[i] = 

32: Color.getHSBColor(c, (float)1.0,(float)1.0); 
33: c += .02; 

34: } 

35: 

36: // cycle through the colors 

37: int i = 0; 

38: while (true) { 

39: setForeground(colors[i]); 

40: repaint(); 

41: itt; 

42: try { Thread.sleep(50); } 

43: catch (InterruptedException e) { } 
44: if (i == colors.length ) i = Q; 

45: } 

46: } 

47: 

48: public void paint(Graphics g) { 

49: g.setFont(f); 

50: g.drawString("All the Swirly Colors", 15,50); 
51: } 

52: } 
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Figure 10.2. 
TheColorSwirl applet. 


Analysis T here are three new things to note about this applet that might look strange to you: 


When the applet starts, the first thing you do (in lines 28 through 34) is to create an 
array of color objects that contains all the colors the text will display. By creating all 
the colors beforehand you can then just draw text in, one at atime it’s faster to 
precompute all the colors at once. 


To create the different colors, a method in the color class called getHsBcolor() creates 
a color object based on values for hue, saturation, and brightness, rather than the 
standard red, green, and blue. This is easier; by incrementing the hue value and 
keeping saturation and brightness constant you can create a range of colors without 
having to know theRGB for each one. If you don’t understand this, don’t worry 
about it; it’s just an easy way to create the color array. 

[| The applet then cycles through the array of colors, setting the foreground to each one 
in turn and calling repaint. W hen it gets to the end of the array, it starts over again 
(line 44), so the process repeats over and over ad infinitum. 


N ow that you understand what the applet does, let’s fix the flicker. Flicker here results because 
each time the applet is painted, there’samoment where thescreen is cleared. Instead of the text 
cycling neatly from red to anice pink to purple, it’s going from red to grey, to pink to grey, to 
purple to grey, and so on— not very nice looking at all. 

Because the screen clearing is all that’s causing the problem, the solution is easy: override 
update() and removethepart wherethe screen gets cleared. It doesn’t really need to get cleared 
anyhow, because nothing is changing except the color of the text. With the screen clearing 
behavior removed from update(), all update needs to do is call paint(). Here's what the 
update() Method looks like in this applet: 


public void update(Graphics g) { 
paint(g); 


With that— with one small three-line addition— no more flicker. W asn’t that easy? 
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Solution Two: Redraw 
Only What You Have To 


For some applets, it won’t be quite that easy. H ere’s another example. In this applet, called 
Checkers, a red oval (a checker piece) moves from a black square to a white square, asif on a 
checkerboard. Listing 10.4 shows the code for this applet, and Figure 10.3 shows the applet 
itself. 


Type Listing 10.4. The Checkers applet. 


1 import java.awt.Graphics; 

2 import java.awt.Color; 

3 

4 public class Checkers extends java.applet.Applet 
5: implements Runnable { 

6: 

7 Thread runner; 

8 int xpos; 

9: 

10: public void start() { 

11: if (runner == null); { 

12: runner = new Thread(this) ; 

13: runner.start()5 

14: } 

15: } 

16: 

17: public void stop() { 

18: if (runner != null) { 

19: runner.stop(); 

20: runner = null; 

21: } 

22: } 

23: 

24: public void run() { 

25: setBackground(Color.blue) ; 

26: while (true) { 

27: for (xpos = 5; xpos <= 105; xpos+=4) { 
28: repaint(); 

29: try { Thread.sleep(100); } 

30: catch (InterruptedException e) { } 
31: } 

32: for (xpos = 105; xpos > 5; xpos -=4) { 
33: repaint(); 

34: try { Thread.sleep(100); } 

35: catch (InterruptedException e) { } 
36: } 

37: } 

38: } 

39: 

40: public void paint(Graphics g) { 

41: // Draw background 

42: g.setColor(Color.black) ; 
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43: g.fillRect(0,0,100,100) ; 
44: g.setColor(Color.white) ; 
45: g.fillRect(101,0,100,100); 
46: 

47: // Draw checker 

48: g.setColor(Color.red) ; 

49: g.f1110val(xpos,5,90,90) ; 
50: } 

51: } 


Figure 10.3. 
The Checkers applet. 


=: 


A m 6Here'sa quick run-through of what this applet does: an instance variable, xpos, keepstrack 

nalyas of the current starting position of the checker (because it moves horizontally, the y stays 

constant and the x changes). In the run) method, you change the value of x and repaint, 
waiting 50 milliseconds between each move. T he checker moves from one side of the screen to 
the other and then moves back (hence the two for loops in that method). 


In the actual paint) method, the background squares are painted (one black and one white), 
and then the checker is drawn at its current position. 


T hisapplet, liketheSwirling C olorsapplet, also hasaterribleflicker. (In line25, thebackground 
is blue to emphasize it, so if you run this applet you'll definitely see the flicker.) 


H owever, thesolution to solving the flicker problem for this applet ismore difficult than for the 
last one, because you actually want to clear thescreen beforethenext frameis drawn. O therwise, 
the red checker won’t have the appearance of leaving one position and moving to anothe;; it’l| 
just leave a red smear from one side of the checkerboard to the other. 


H ow do you get around this? Y ou still clear the screen, in order to get the animation effect, but, 
rather than clearing the entire screen, you clear only the part that you actually changed. By 
limiting the redraw to only asmall area, you can eliminate much of the flicker you get from 
redrawing the entire screen. 
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To limit what gets redrawn, you need a couple of things. First, you need a way to restrict the 
drawing areaso that each timepaint() iscalled, only the part that needsto get redrawn actually 
gets redrawn. Fortunately, this is easy by using a mechanism called clipping. 


NEWe- Clipping, part of the graphics class, enables you to restrict the drawing area to a small 
TERM portion of the full screen; although the entire screen may get instructions to redraw, only 
the portions inside the clipping area are actually drawn. 


Thesecond thing you need isa way to keep track of the actual area to redraw. Both theleft and 
right edges of thedrawing area change for each frame of theanimation (onesideto draw thenew 
oval, the other to erase the bit of the oval left over from the previous frame), so to keep track of 
those two x values, you need instance variables for both the left side and the right. 


W ith thosetwo conceptsin mind, let’sstart modifying the C heckers applet to redraw only what 
needsto beredrawn. First, you'll add instance variablesfor theleft and right edgesof thedrawing 
area. Let’s call those instance variables ux1 and ux2 (u for update), where ux1 is the left side of 
the area to draw and ux2 the right. 


int ux1,ux2; 


N ow let’s modify the run) method so that it keeps track of the actual area to be drawn, which 
you would think is easy— just update each side for each iteration of the animation. H ere, 
however, things can get complicated because of the way J ava uses paint() and repaint(). 


The problem with updating the edges of the drawing area with each frame of the animation is 
that for every call to repaint () theremay not bean individual corresponding paint() . If system 
resources get tight (because of other programs running on the system or for any other reason), 
paint () May not get executed immediately and several calls to paint () May queueup waiting 
for their turn to changethepixelson thescreen. In thiscase, rather than trying to makeall those 
callsto paint) in order (and be potentially behind all the time), Java catches up by executing 
only the most recent call to paint ) and skips all the others. 


If you update the edges of thedrawing areawith each repaint() , and acoupleof callsto paint () 
are skipped, you end up with bits of the drawing surface not being updated and bits of the oval 
left behind. T here’sa simple way around this: update the leading edge of the oval each timethe 
frame updates, but only update the trailing edge if the most recent paint has actually occurred. 
This way, if a couple of calls to paint() get skipped, the drawing area will get larger for each 
frame, and when paint) finally gets caught up, everything will get repainted correctly. 


Yes, thisishorrifyingly complex. If | could have written this applet simpler, | would have, but 
without this mechanism the applet will not get repainted correctly. Let’s step through it slowly 
in the code so you can get a better grasp of what’s going on at each step. 


Let’sstart with run() , whereeach frameof theanimation takesplace. H ere’swhereyou calculate 
each side of the drawing area based on the old position of the oval and the new position of the 
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oval. W hen the oval is moving toward the left side of the screen, this is easy. T he value of uxt 
(the left side of the drawing area) is the previous oval’s x position (xpos), and the value of ux2 
is the x position of the current oval plus the width of that oval (90 pixels in this example). 


H ere’s what the old run() method looked like, to refresh your memory: 


public void run() { 
setBackground(Color.blue) ; 
while (true) { 
for (xpos = 5; xpos <= 105; xpost=4) { 
repaint(); 
try { Thread.sleep(100); } 
catch (InterruptedException e) { } 


for (xpos = 105; xpos > 5; xpos -=4) { 
repaint(); 
try { Thread.sleep(100); } 
catch (InterruptedException e) { } 


} 
} 


In the first tor loop in the run() method, wherethe oval is moving towards the right, you first 
update ux2 (the right edge of the drawing area): 


ux2 = xpos + 90; 


Then, after the repaint() hasoccurred, you update ux1 to reflect the old x position of the oval. 
H owever, you want to update this value only if the paint actually happened. H ow can you tell 
if the paint actually happened? You can reset ux1 in paint() to agiven value (a), and then test 
to see whether you can update that value or whether you haveto wait for the paint,) to occur: 
if (ux1 == @) ux1 = xpos; 
H ere’s the new, completed for loop for when the oval is moving to the right: 
for (xpos = 5; xpos <= 105; xpost+=4) { 

ux2 = xpos + 90; 

repaint(); 

try { Thread.sleep(100); } 

catch (InterruptedException e) { } 

if (ux1 == 0) ux1 = xpos; 


} 


W hen the oval ismoving to the left, everything flips. ux1, theleft side, isthe leading edge of the 
oval that getsupdated every time, and uxz, theright side, hasto waitto makesureit gets updated. 
So, in the second for loop, you first update ux1 to be the x position of the current oval: 


ux1 = xpos; 
Then, after the repaint ) iscalled, you test to make sure the paint happened and update ux2: 


if (ux2 == @) ux2 = xpos + 90; 
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H ere’s the new version of the secod for loop inside run(): 


for (xpos = 105; xpos > 5; xpos -=4) { 

ux1 = xpos; 

repaint(); 

try { Thread.sleep(100); } 

catch (InterruptedException e) { } 

if (ux2 == @) ux2 = xpos + 90; 
} 
T hose are the only modifications run() needs. Let’s override update to limit the region that is 
being painted to the left and right edges of the drawing area that you set insiderun(). To clip 
thedrawingareato aspecific rectangle, usethecliprect() Method. clipRect(), likedrawRect(), 
fillrRect(), and clearRect(), iS defined for graphics objects and takes four arguments: x and 


y starting positions, and width and height of the region. 


H ere’s whereux1 and ux2 comeinto play. ux1 isthe x point of thetop corner of the region; then 
use ux2 to get the width of the region by subtracting ux1 from that value. Finally, to finish 
update(), YOU Call paint(): 
public void update(Graphics g) { 

g.clipRect(ux1, 5, ux2 - ux1, 95); 

paint(g); 

} 

N otethat with the clipping region in place, you don’t haveto do anything to theactual paint () 
method. paint() goes ahead and drawsto the entire screen each time, but only the areas inside 
the clipping region actually get changed on screen. 


You need to update the trailing edge of each drawing area inside paint() in case several calls to 
paint() wereskipped. Because you aretesting for a value of a insiderun(), you merely reset uxt 
and ux2 to o after drawing everything: 


ux1 = ux2 = Q; 


T hose are the only changes you have to make to this applet in order to draw only the parts of 
the applet that changed (and to manage the case where some frames don’t get updated 
immediately). Although thisdoesn’t totally diminateflickeringin theanimation, it doesreduce 
it a great deal. Try it and see. Listing 10.5 shows the final code for the C heckers applet. 


Type Listing 10.5. The final Checkers applet. 
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: import java.awt.Graphics; 
: import java.awt.Color; 


1 

2 

3: 

4: public class Checkers2 extends java.applet.Applet implements Runnable { 
5: 

6 

7 


Thread runner; 
int xpos; 


int ux1,ux2; 


public void start() { 


} 


if (runner == null); { 
runner = new Thread(this 
runner.start()5 


public void stop() { 


} 


if (runner != null) { 
runner.stop() 5; 
runner = null; 


public void run() { 


setBackground(Color.blue) ; 
while (true) { 


for (xpos = 5; xpos <= 105; xpost=4) { 


ux2 = xpos + 90; 
repaint(); 
try { Thread.sleep(1 


catch (InterruptedException e) { } 


if (uxt == 0) uxt = 


for (xpos = 105; xpos > 5; xpos -=4) { 


ux1 = xpos; 
repaint(); 
try { Thread.sleep(1 


catch (InterruptedException e) { } 


if (ux2 == 0) ux2 = 


} 


} 
public void update(Graphics g) { 


} 


g.clipRect(ux1, 5, ux2 - ux1 
paint (g); 


public void paint(Graphics g) { 


// Draw background 
g.setColor(Color.black) ; 
g.fillRect(0,0,100,100); 
g.setColor(Color.white) ; 
g.fi1l1Rect(101,0,100,100) ; 


// Draw checker 
g.setColor(Color.red) ; 
g.f1110val(xpos,5,90,90) ; 


// reset the drawing area 
uxX1 = ux2 = Q; 


)3 


00); } 


xpos; 


00); } 


xpos + 90; 


» 95); 


191 


®@ DAY @ 
Simple Animation and Threads 


Summary 


Congratulations on getting through D ay 10!T hisday was abit rough; you’velearned alot, and 
it all might seem overwhelming. You learned about a plethora of methods to useand override: 
start(), stop(), paint(), repaint(), run(), aNd update()— and you got asolid foundation in 
creating and using threads. 
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After today, you're over the worst hurdles in terms of understanding applets. O ther than 
handling bitmap images, which you'll learn about tomorrow, you now have the basic 
background to create just about any animation you want in J ava. 


Q&A 


Q 


Q 


Why all the indirection with paint and repaint and update and all that? Why not 
have a simple paint method that just puts stuff on the screen when you want it 
there? 


TheJava AWT toolkit enables you to nest drawable surfaces within other drawable 
surfaces. W hen a paint takes place, all the parts of the system are redrawn, starting 
from the outermost surface and moving downward into the most nested one. Because 
the drawing of your applet takes place at the same time everything elseis drawn, your 
applet doesn’t get any special treatment. Your applet will be painted when everything 
else is painted. Although with this system you sacrifice some of the immediacy of 
instant painting, it enables your applet to co-exist with the rest of the system more 
cleanly. 


Are) ava threads like threads on other systems? 


A Javathreads have been influenced by other thread systems, and if you're used to 


working with threads, many of the concepts in Java threads will be very familiar to 
you. You learned the basics today; you'll learn more next week on Day 17. 

When an applet uses threads, | just have to tell the thread to start and it starts, 
and tell it to stop and it stops? That’s it? | don’t have to test anything in my loops 
or keep track of its state? Is just stops? 

It just stops. When you put your applet into a thread, J ava can control the execution 
of your applet much more readily. By causing the thread to stop, your applet just 
stops running, and then resumes when the thread starts up again. Y¢s, it’s all auto- 
matic. N eat, isn’t it? 


pe) 


The Swirling Colors applet seems to display only five or six colors. W hat’s going 
on here? 


Thisis the same problem that you ran into yesterday wherein, on some systems, there 
might not be enough colors to be able to display all of them reliably. If you’re running 
into this problem, other than upgrading your hardware, you might try quitting other 
applications running on your system that use color. O ther browsers or color tools in 
particular might be hogging colors that J ava wants to be able to use. 


Even with the changes you made, the Checkers applet still flickers. 


And, unfortunately, it will continue to do so. Reducing the size of the drawing area by 
using clipping does significantly reduce the flickering, but it doesn’t stop it entirely. 
For many applets, using either of the methods described today may be enough to 
reduce animation flicker to the point where your applet works right. T o get totally 
flicker-free animation, you'll use a technique called double-buffering, which you'll 
learn about tomorrow. 
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Animations are fun and easy to do in J ava, but there’s only so much you can do with the built- 
in Java methods for lines and fonts and colors. For really interesting animations, you have to 
provide your own images for each frame of the animation— and having soundsisnice, as well. 
Today, you'll do more with animations, incorporating images and sounds into J ava applets. 


Specifically, you'll explore the following topics: 
(| Using images— getting them from the server, loading them into J ava, and displaying 
them in your applet 
Creating animations by using images, including an extensive example 
U sing sounds— getting them and playing them at the appropriate times 
Sun’s Animator applet— an easy way to organize animations and sounds in J ava 
D ouble-buffering— hardcore flicker avoidance 


Retrieving and Using Images 


Basic image handling in J ava is easy. T he image class in java.awt provides abstract methods to 
represent common image behavior, and special methods defined in Appiet and Graphics give 
you everything you need to load and display imagesin your applet aseasily asdrawingarectangle. 
In this section, you'll learn about how to get and draw imagesin your J ava applets. 


Getting I mages 


To display an imagein your applet, you first must load that image over the net into your J ava 
program. Images are stored as separate files from your J ava class files, so you have to tell J ava 
where to find then. 


The applet Class provides a method called getImage, which loads an image and automatically 
creates an instance of the 1mage class for you. To use it, all you have to do is import the 
java.awt . Image Class, and then givegetImage theU RL of theimageyou want to load. T hereare 
two ways of doing the latter step: 


(| The getImage method with a single argument (an object of type URL) retrieves the 
image at that URL. 


(] The getImage method with two arguments: the base URL (also aurt object) and a 
string representing the path or filename of the actual image (relative to the base). 


Although thefirst way may seem easier (just plugin theU RL asaurt object), thesecond ismore 
flexible. Remember, because you're compiling] ava files, if you includeahard-coded U RL of an 
image and then move your files around to a different location, you have to recompile all your 
Java files. 
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Thelatter form, therefore, isusually theoneto use. T heppiet Class also providestwo methods 
that will help with the base URL argument to getImage: 


T he getDocumentBase() Method returns a urL object representing the directory of the 
HTML filethat contains this applet. So, for example, if the HT ML fileis located at 
http: //www.myserver.com/htmlfiles/javahtml/, getDocumentBase returns aURL 
pointing to that path. 

T he getcodeBase() Method returns a string representing the directory in which this 
applet is contained— which may or may not be the same directory asthe HT ML file, 
depending on whether the copepase attribute in <appLeT> is set or not. 


W hether you use getDocumentBase() OF getCodebase() depends on whether your images are 
relativeto your HTML files or relative to your J ava class files. U se whichever one applies better 
to your situation. N ote that either of these methods is more flexible than hard-coding aU RL 
or pathname into the getImage method; using either getDocumentBase OF getCodeBase enables 
you to move your HT ML files and applets around and J ava can still find your images. 


H ereareafew examplesof getImage, to giveyou an ideaof how to useit. T hisfirst call to get rmage 
retrieves the file at that specific U RL ("http: //www.server.com/files/image.git"). If any part 
of that URL changes, you haveto recompile your J ava applet to takethe new path into account: 


Image img = getImage( 
new URL("http://www.server.com/files/image.gif")); 


In the following form of getrmage, theimagegif fileisin the same directory astheH TM L files 
that refer to this applet: 


Image img = getImage(getDocumentBase(), "“image.gif") 
In this similar form, the file image.gif isin the same directory as the applet itself: 
Image img = getImage(getCodeBase(), "image.gif") 


If you have lots of image files, it’s common to put them into their own subdirectory. T his form 
Of getImage looks for the file image.gif in the directory images, which, in turn, isin the same 
directory as the J ava applet: 


Image img = getImage(getCodeBase(), "images/image.gif") 


If Java can’t find the file you've indicated, getImage returns nu11. Your program will continue 
to run— you just won't see that image on your screen when you try to draw it. 


Note: Currently, Java supports imagesin the GIF and JPEG formats. O ther image 
formats may be available later; however, for now, your images should bein either 
GIF or JPEG. 
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Drawing I mages 


All that stuff with gettmage does nothing except go off and retrieve an image and stuff it into 
an instance of the image class. N ow that you have an image, you have to do something with it. 


The most likely thing you're going to want to do is display it as you would arectangle or atext 
string. The Graphics Class provides two methods to do just that, both called drawrmage. 


Thefirst version of drawImage takes four arguments: theimageto display, thex and y positions 
of the top left corner, and this: 
void paint() { 

g.drawImage(img, 10, 10, this); 
} 
This first form does what you would expect it to: it draws the image in its original dimensions 
with the top left corner at the given x and y positions. Listing 11.1 shows the code for a very 
simple applet that loads in an image called ladybug.gif and displays it. Figure 11.1 shows the 
obvious result. 


Type Listing 11.1. The Ladybug applet. 


1: import java.awt.Graphics; 

2: import java.awt.Image; 

3: 

4: public class LadyBug extends java.applet.Applet { 
5: 

6: Image bugimg; 

7: 

8: public void init() { 

9: bugimg = getImage(getCodeBase(), 
10: "images/ladybug.gif"); 
11: } 
12: 
13: public void paint(Graphics g) { 
14: g.drawImage(bugimg,10,10,this) ; 
15: } 
16: } 


A Fl ™ The second form of drawImage takes six arguments: the image to draw, the x and y 
MalVSS coordinates, a width and height of the image bounding box, and this. If the width and 
height arguments for the bounding box are smaller or larger than the actual image, the 
image is automatically scaled to fit. U sing those extra arguments enables you to squeeze and 
expand images into whatever space you need them to fit in (keep in mind, however, that there 

may be some image degradation from scaling it smaller or larger than its intended size). 


O nehelpful hint for scaling imagesisto find out thesize of theactual imagethat you’veloaded, 
so you can then scale it to a specific percentage and avoid distortion in either direction. T wo 
methods defined for the image class enable you do this: getwidth() and getHeight(). Both take 
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asingleargument, an instance of Imageobserver, which isused to track theloading of theimage 
(more about this later). M ost of the time, you can use just this as an argument to either 


getWidth() Of getHeight(). 


Figure 11.1. 
TheLadybug image 


If you stored the ladybug image in a variable called bugimg, for example, this line returns the 


width of that image, in pixels: 


theWidth = bugimg.getWidth(this) ; 


Listing 11.2 shows another use of the ladybug image, this time scaled several times to different 


sizes (Figure 11.2 shows the result). 


Listing 11.2. More Ladybugs, scaled. 


1 import java.awt.Graphics; 

2: import java.awt. Image; 

3: 

4: public class LadyBug2 extends java.applet.Applet { 
5: 

6: Image bugimg; 

7: 

8 public void init() { 

9 bugimg = getImage(getCodeBase(), 

10: “images/ladybug.gif"); 

11: } 

12: 

13: public void paint(Graphics g) { 

14: int iwidth = bugimg.getWidth(this) ; 
15: int iheight = bugimg.getHeight (this) ; 
16: int xpos = 10; 

17: 

18: // 25 % 


continues 


199 


® DAY @ 


11 More Animation, Images, and Sound 


Listing 11.2. continued 


19: g.drawImage(bugimg, xpos, 10, 

20: iwidth / 4, iheight / 4, this); 
21: 

22: // 50 % 

23: xpos += (iwidth / 4) + 10; 

24: g.drawImage(bugimg, xpos , 10, 

25: iwidth / 2, iheight / 2, this); 
26: 

27: 1/1 100% 

28: xpos += (iwidth / 2) + 10; 

29: g.drawImage (bugimg, xpos, 10, this); 
30: 

31: // 150% x, 25% y 

32: g.drawImage(bugimg, 10, iheight + 30, 
33: (int) (iwidth * 1.5), iheight / 4, this); 
34: 

35: } 


Figure 11.2. 


T he second Ladybug applet. & 


ans 


I've been steadfastly ignoring mentioning that last argument to drawImage: the mysterious 
this, which also appears as an argument to getwidth() and getHeight(). Why is this 
argument used? I ts official use is to passin an object that functions as an | mageO bserver 


(that is, an object that implements the ImageO bserver interface). | mage observers enable you 
to watch the progress of how far along an imageisin the loading process and to make decisions 


200 


when the image is only fully or partially loaded. T he appiet class, which your applet inherits 
from, contains default behavior for watching for images that should work in the majority of 
cases— hence, the this argument to drawImage(), getWidth(), aNd getHeight(). The only 
reason you'll want to use an alternate argument in its placeis if you are tracking lots of images 
loading synchronously. See the java.awt. image. ImageObserver Class for more details. 


Modifying Images 

In addition to the basics and handling images described in this section, the javaawt.image 
package providesmoreclasses and interfaces that enableyou to modify images and their internal 
colors, or to createbitmap images by hand. M ost of theseclasses require background knowledge 
in image processing, including a good grasp of color models and bitwise operations. All these 
things are outside the scope of an introductory book on J ava, but if you have this background 
(or you’re interested in trying it out), the classesin java.awt.image will be helpful to you. T ake 
alook at the example codefor creating and using images that comes with the] ava development 
kit for examples of how to use the image classes. 


Creating Animation Using Images 


Creating animations by usingimagesismuch thesameas creating images by using fonts, colors, 
or shapes— you use the same methods, the same procedures for painting, repainting, and 
reducing flicker that you learned about yesterday. The only difference is that you have a stack 
of images to flip through rather than a set of painting methods. 


Probably the best way to show you how to useimagesfor animation is simply to walk through 
an example. H ere’s an extensive one of an animation of a small cat called N eko. 


An Example: Neko 


N eko was a small Macintosh animation/game written and drawn by Kenji Gotoh in 1989. 
“N eko” is] apanesefor “cat,” and theanimation isof asmall kitten that chasesthemouse pointer 
around the screen, sleeps, scratches, and generally acts cute. The N eko program has since been 
ported to just about every possible platform, as well as rewritten as a popular screensaver. 


For this example, you’ll implement a small animation based on the original N eko graphics. 
Because the original N eko the cat was autonomous (it could “sense” the edges of the window 
and turn and run in adifferent direction), thisapplet merely causes N eko to run in from theleft 
side of thescreen, stop in the middle, yawn, scratch its ear, sleep alittle, and then run off to the 
right. 


201 


® DAY @ 
More Animation, Images, and Sound 


Note: T his is by far the largest of the applets discussed in this book, and if | either 
print it here and then describe it, or build it up line by line, you'll be here for days. 
Instead, |’m going to describe the parts of this applet independently, and |’m going 
to leave out the basics— the stuff you learned yesterday about starting and stopping 
threads, what the run() method does, and so on. All the code is printed later today 
so that you can put it all together. 


Before you begin writing J ava code to construct an animation, you should have all the images 
that form the animation itself. For this version of N eko there arenineof then (the original has 
36), as shown in Figure 11.3. 


Theta tra $3 


I’ve stored these images in a subdirectory of my applet directory called, appropriately, images. 
W here you store your imagesisn’t all theimportant, but you should take note of where you've 
put them because you'll need that information 


N ow, onto the applet. T he basic idea of animation by using images is that you have a set of 
images, and you display them oneat atime, rapidly, so they give the appearance of movement. 
T he easiest way to manage thisin J avaisto store theimagesin an array of classtmage, and then 
to have a special variable that stores a reference to the current image. 


Technical Note: T he java.util class contains a class (HashTable) that implements 
ahash table For large amounts of images, a hash table is faster to find and retrieve 
images from than an array is. Because you have a relatively small amount of images 
here, and because arrays are easier to deal with, I'll use an array here. 


For theN eko applet, you'll includeinstance variables to implement both these things: an array 
to hold the images called nekopics, and a variable of type 1mage to hold the current image: 


Image nekopics[] = new Image[9]; 
Image currentimg; 


Because you'll need to pass the position of the current image around between the methodsin 
this applet, you'll also need to keep track of the current x and y positions. The y stays constant 
for this particular applet, but the x may vary. let’s add two instance variables for those two 
positions: 
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int xpos; 

int ypos = 50; 

N ow, onto thebody of theapplet. D uringtheapplet’s initialization, you'll read in all theimages 
and storethem in the nekopics array. T hisisthe sort of operation that works especially well in 
an init() method. 


Given that you have nine images with nine different filenames, you could do a separate call to 
get Image for each one You can saveat least alittle typing, however, by creating an array of the 
file names (nekosrc, an array of strings) and then just using a for loop to iterate over each one. 
H ere’sthe init) method for theN eko applet that loads all the imagesinto thenekopics array: 


public void init() { 


String nekosrc[] = { "right1.gif", "right2.gif", 
"stop.gif", "yawn.gif", "scratch1.gif", 
"scratch2.gif","sleep1.gif", "“sleep2.gif", 
"“awake.gif" }; 
for (int i=0; i < nekopics.length; i++) { 
nekopics[i] = getImage(getCodeBase(), 
"images/" + nekosrc[i]); 
} 
} 
N oteherein the call to getImage that the directory these images are stored in isincluded as part 


of the path. 

With the images loaded, the next step is to start animating the bits of the applet. You do this 
inside the applet’s thread’s run() method. In this applet, N eko does five main things: 

L] Runsin from the left side of the screen 

Stops in the middle and yawns 

Scratches four times 

Sleeps 

W akes up and runs off to the right side of the screen 


Because you could animate this applet by merely painting the right image to the screen at the 
right time, it makes more sense to write this applet so that many of N eko’s activities are 
contained in individual methods. T hisway, you can reuse some of the activities (the animation 
of N eko running, in particular) if you want N eko to do things in a different order. 


Let's start by creating a method to make N eko run. Because you’re going to be using this one 
twice, making it generic is a good plan. Let’s create the nekorun method, which takes two 
arguments: the x position to start, and thex position to end. N eko then runs between thosetwo 
positions (the y remains constant). 


T here are two images that represent N eko running; so, to create the running effect, you need 
to alternate between those two images (stored in positions 0 and 1 of the image array), as well 
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as move them across the screen. The moving part is a simple for loop between the start and 
end arguments, setting the global x position to the current loop value. Swapping the images 
means merely testing to see which one is active at any turn of the loop and assigning the other 
oneto the current image. Finally, at each new frame, you'll call repaint and sleep for a bit. 


Actually, given that during this animation there will be alot of sleeping of various intervals, it 
makes sense to create a method that does the sleeping for the appropriate time interval. Call it 
pause— here's its definition: 

void pause(int time) { 


try { Thread.sleep(time); } 
catch (InterruptedException e) { } 


Back to thenekorun method. T 0 Summarize, nekorun iteratesfrom the start position to theend 
position. For each turn of the loop, it sets the current x position, sets currentimg to the right 
animation frame, calls repaint, and pauses. Got it? H ere’s the definition of nekorun: 
void nekorun(int start, int end) { 
for (int i = start; i < end; it=10) { 
this.xpos = i; 
// swap images 


if (currentimg == nekopics[Q]) 
currentimg = nekopics[1]; 

else if (currentimg == nekopics[1]) 
currentimg = nekopics[0]; 

repaint(); 

pause(150); 


} 
} 
N otethat in that second lineyou increment theloop by ten pixels. W hy ten pixels, and not, say, 
five or eight? The answer is determined mostly through trial and error to see what looks right. 
Ten seems to work best for the animation. When you write your own animations, you have to 
play with both the distances and the sleep times until you get an animation you like 


Speaking of repaint, let’s cover the paint() method, which paints each frame. H ere the paint 
method istrivially simple; all paint isresponsiblefor ispainting thecurrent imageat thecurrent 
xand y positions. All that information is stored in global variables, so the paint method hasonly 
asingleline in it: 


public void paint(Graphics g) { 
g.drawImage(currentimg, xpos, ypos, this); 


N ow let’s back up to the run() method, where the main processing of this animation is 
happening. You've created the nekorun method; in run you'll call that method with the 
appropriate values to make N eko run from the right edge of the screen to the center: 


// run from one side of the screen to the middle 

nekorun(@, this.size().width / 2); 

T hesecond major thing N eko doesin this animation is stop and yawn. You havea single frame 
for each of these things (in positions 2 and 3 in the array), so you don’t really need a separate 
method for them. All you need to do is set the appropriate image, call repaint(), and pausefor 
the right amount of time. T his example pauses for a second each time for both stopping and 
yawning— again, using trial and error. H ere’s the code: 

// stop and pause 

currentimg = nekopics[2]; 


repaint(); 
pause(1000) ; 


// yawn 

currentimg = nekopics[3]; 

repaint(); 

pause (1000) ; 

Let'smoveon to thethird part of the animation: scratching. T here’sno horizontal for this part 
of the animation. You alternate between the two scratching images (stored in positions 4 and 
5 of the image array). Because scratching is a distinct action, however, let’s create a separate 
method for it. 


Th@ nekoscratch method takes a single argument: the number of times to scratch. W ith that 
argument, you can iterate, and then, insidetheloop, alternatebetween thetwo scratchingimages 
and repaint each time: 


void nekoscratch(int numtimes) { 
for (int i = numtimes; i > 0; i--) { 

currentimg = nekopics[4]; 
repaint(); 
pause(150); 
currentimg = nekopics[5]; 
repaint(); 
pause(150); 


} 
Inside the run method, you can then call nekoscratch with an argument of four: 


// scratch four times 

nekoscratch(4) ; 

O nward! After scratching, N eko sleeps. Again, you have two images for sleeping (in positions 
6 and 7 of the array), which you'll alternate a certain number of times. H ere’s the nekosleep 
method, which takes a single number argument, and animates for that many “turns”: 

void nekosleep(int numtimes) { 


for (int i = numtimes; i > 0; i--) { 
currentimg = nekopics[6]; 
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repaint(); 
pause(250) ; 
currentimg = nekopics[7]; 
repaint(); 
pause(250) ; 
} 
} 


Call nekosleep in the run() method like this: 


// sleep for 5 "turns" 

nekosleep(5) ; 

Finally, to finish off the applet, N eko wakes up and runs off to theright side of the screen. wake 
up isyour last imagein thearray (position eight), and you can reusethenekorun method tofinish: 
// wake up and run off 

currentimg = nekopics[8]; 

repaint(); 

pause(500) ; 

nekorun(xpos, this.size().width + 10); 

T here’sonemorethingleft to do to finish theapplet. T heimagesfor theanimation all havewhite 
backgrounds. D rawing thoseimages on the default applet background (amedium grey) means 
an unsightly white box around each image. T o get around the problem, merely set the applet’s 
background to white at the start of the run() method: 


setBackground(Color.white) ; 


Got all that? T here’sa lot of codein this applet, and alot of individual methods to accomplish 
arather simple animation, but it’s not all that complicated. T he heart of it, asin the heart of all 
Java animations, isto set up the frame and then call repaint () to enablethescreen to bedrawn. 


N otethat you don’t do anything to reduce theamount of flicker in this applet. It turns out that 
theimagesaresmall enough, and thedrawingareaalso small enough, that flicker isnot aproblen 
for thisapplet. It’s alwaysagood ideato write your animationsto do thesimplest thingfirst, and 
then add behavior to make them run cleaner. 


To finish up this section, Listing 11.3 shows the complete code for the N eko applet. 


Type Listing 11.3. The final Neko applet. 


36: import java.awt.Graphics; 
37: import java.awt.Image; 
38: import java.awt.Color; 


39: 

40: public class Neko extends java.applet.Applet 
41: implements Runnable { 

42: 

43: Image nekopics[] = new Image[9]; 

44: Image currentimg; 

45: Thread runner; 

46: int xpos; 


int ypos = 50; 


public void init() { 
String nekosrc[] = { "right1.gif", "right2.gif", 
"stop.gif", "yawn.gif", "scratch1.gif", 
"scratch2.gif","sleep1.gif", "“sleep2.gif", 
"“awake.gif" }; 


for (int i=0; i < nekopics.length; i++) { 
nekopics[i] = getImage(getCodeBase(), 
“images/" + nekosrc[i]); 


} 


public void start() { 
if (runner == null) { 
runner = new Thread(this) ; 
runner.start(); 


i 


public void stop() { 
if (runner != null) { 
runner.stop(); 
runner = null; 


} 


public void run() { 
setBackground(Color.white) ; 


// run from one side of the screen to the middle 
nekorun(@, this.size().width / 2); 


// stop and pause 
currentimg = nekopics[2]; 
repaint(); 

pause(10Q0) ; 


// yawn 

currentimg = nekopics[3]; 
repaint(); 

pause(10Q0) ; 


// scratch four times 
nekoscratch(4) ; 


// sleep for 5 "turns" 
nekosleep(5); 


// wake up and run off 
currentimg = nekopics[8]; 

repaint(); 

pause(5QQ) ; 

nekorun(xpos, this.size().width + 10); 


continues 
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Listing 11.3. continued 


102: } 

103: 

104: void nekorun(int start, int end) { 

105: for (int i = start; i < end; it=10) { 
106: this.xpos = i; 

107: // swap images 

108: if (cCurrentimg == nekopics[Q]) 
109: currentimg = nekopics[1]; 

110: else if (currentimg == nekopics[1]) 
111: currentimg = nekopics[Q]; 

112: else currentimg = nekopics[Q]; 
113: 

114: repaint(); 

115: pause(150); 

116: } 

117: } 

118: 

119: void nekoscratch(int numtimes) { 

120: for (int i = numtimes; i > 0; i--) { 
121: currentimg = nekopics[4]; 

122: repaint(); 

123: pause(150); 

124: currentimg = nekopics[5]; 

125: repaint(); 

126: pause(150) ; 

127: } 

128: } 

129: 

130: void nekosleep(int numtimes) { 

131: for (int i = numtimes; i > 0; i--) { 
132: currentimg = nekopics[6]; 

133: repaint(); 

134: pause(250) ; 

135: currentimg = nekopics[7]; 

136: repaint(); 

137: pause(250) ; 

138: } 

139: 

140: void pause(int time) { 

141: try { Thread.sleep(time); } 

142: catch (InterruptedException e) { } 
143: } 

144: 

145: public void paint(Graphics g) { 

146: g.drawImage(currentimg, xpos, ypos, this); 
147: } 

148: } 


208 


Retrieving and Using Sounds 


Java has built-in support for playing sounds in conjunction with running animations or for 
sounds on their own. In fact, support for sound, like support for images, is built into theappiet 
and awt classes, so using sound in your J ava applets is as easy as loading and using images. 


Currently, the only sound format that J ava supports isSun’s AU format, sometimes called p- 
law format. AU filestend to be smaller than sound filesin other formats, but the sound quality 
isnot very good. If you're especially concerned with sound quality, you may want your sound 
clipsto bereferencesin thetraditional H T M L way (aslinksto external files) rather than included 
in aJava applet. 


T hesimplest way to retrieveand play asound isthrough the piay() method, part of the appiet 
class and therefore availableto you in your applets. T hep1ay() method issimilar to theget Image 
method in that it takes one of two forms: 


play with one argument, aur object, loads and plays the given audio clip at that 
URL. 

play() with two arguments, onea base urt and one a pathname, loads and plays that 
audio file The first argument can most usefully be either a call to getDocumentBase() 
Or getCodeBase(). 


For example, the following line of code retrieves and plays the sound meow.au, which is 
contained in the audio directory. T he audio directory, in turn, is located in the same directory 
as this applet: 


play(getCodeBase(), "audio/meow.au") ; 


The piay method retrieves and plays the given sound as soon as possible after it is called. If it 
can’t find the sound, you won't get an error; you just won't get any audio when you expect it. 


If you want to play asound repeatedly, start and stop the sound clip, or run the clip asaloop 
(play it over and over), thingsareslightly morecomplicated— but not much moreso. In thiscase, 
you usethe applet method getaudioc1ip() to load the sound clip into an instance of the class 
AudioClip (part of java.applet— don’t forget to import it) and then operate directly on that 
AudioClip object. 


Suppose, for example, that you havea sound loop that you want to play in the background of 
your applet. In your initialization code, you can use this line to get the audio clip: 


AudioClip clip = getAudioClip(getCodeBase(), 
“audio/loop.au"); 


Then, to play the clip once, use the piay method: 


clip.play(); 
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To stop acurrently playing sound clip, usethe stop) method: 
clip.stop(); 

To loop the clip (play it reoeatedly), use the 1o0p() method: 
clip.loop(); 


If the getAudioclip method can’t find thesound you indicate, or can’t load it for any reason, 
theaudioclip variableisset to nui1.|t’sagood ideato test for thiscasein your codebeforetrying 
to play theaudio clip— , becausetryingto call thepiay(), stop(), aNd loop() methodson anu11 
object will result in an error (actually, an exception). 


In your applet, you can play as many audio clips as you need; all the sounds you use play 
concurrently as your applet executes. 


N otethat if you usea background sound— asound clip that loops repeatedly— that sound clip 
will not stop playing automatically when you suspend the applet’s thread. T hismeansthat even 
if your reader moves to another page, thefirst applet’s sounds will continueto play. You can fix 
this problem by stopping the applet’s background sound in your stop() method: 
public void stop() { 
if (runner != null) { 
if (bgsound!= null) 
bgsound.stop() ; 
runner.stop() ; 
runner = null; 
} 
} 
Listing 11.4 shows a simple framework for an applet that plays two sounds: the first, a 
background sound called loop.au, plays repeatedly. Thesecond, ahorn honking (beep.au) plays 
every fiveseconds. (I won’t bother giving you apictureof thisapplet, becauseit doesn’t actually 
display anything other than a simple string to the screen). 


Type Listing 11.4. The AudioLoop applet. 


: import java.awt.Graphics; 
: import java.applet.AudioClip; 


: public class AudioLoop extends java.applet.Applet 
implements Runnable { 


AudioClip bgsound; 
AudioClip beep; 
Thread runner; 


public void start() { 
if (runner == null) { 
runner = new Thread(this) ; 
runner.start()5 
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43: } 


} 


public void stop() { 
if (runner != null) { 
if (bgsound != null) bgsound.stop(); 
runner.stop(); 
runner = null; 


} 


public void init() { 
bgsound = getAudioClip(getCodeBase(), “audio/loop.au") ; 
beep = getAudioClip(getCodeBase(), "“audio/beep.au") ; 

} 


public void run() { 
if (bgsound != null) bgsound.1loop(); 
while (runner != null) { 
try { Thread.sleep(5000); } 
catch (InterruptedException e) { } 
if (bgsound != null) beep.play(); 


} 


public void paint(Graphics g) { 
g.drawString("Playing Sounds....", 10, 10); 


Sun’s Animator Applet 


Because most J ava animations have alot of codein common, being able to reuse all that code 
as much as possible makes creating animations with images and sounds much easier, particular 
for Javadevelopers who aren’t asgood at the programming sideof] ava. For just thisreason, Sun 
provides an Animator class as part of the standard J ava release. 


TheAnimator applet provides asimple, general-purpose animation interface. You compilethe 
code and create an HT ML file with the appropriate parameters for the animation. U sing the 
Animator applet, you can do the following: 


Create an animation loop, that is, an animation that plays repeatedly. 
Add a soundtrack to the applet. 

Add sounds to be played at individual frames. 

Indicate the speed at which the animation is to occur. 


Specify the order of the frames in the animation— which means that you can reuse 
frames that repeat during the course of the animation. 


211 


® DAY @ 
More Animation, Images, and Sound 


Even if you don’t intend to use Sun’s Animator code, it’s a great example of how animations 
work in Java and the sorts of clever tricks you can usein a] ava applet. 


T he Animator Classis part of theJ ava distribution (in the demo directory), or you can find out 
more information about it at the] ava home page, http: //java.sun.com. 


More About Flicker: D ouble-B uffering 


Yesterday, you learned two simple ways to reduce flickering in animations. Although you 
learned specifically about animations using drawing, flicker can also result from animations 
using images. In addition to thetwo flicker-reducing methods described yesterday, thereis one 
other way to reduce flicker in an application: double buffering. 


NEWe- With double buffering, you create a second surface (offscreen, so to speak), do all your 

TERM painting to that offscreen surface, and then draw the whole surface at onceonto the actual 
applet (and onto the screen) at the end— rather than drawing to the applet’s actual graphics 
surface. Because all the work actually goes on behind the scenes, there's no opportunity for 
interim parts of the drawing process to appear accidentally and disrupt the smoothness of the 
animation. 


D ouble-buffering isn’t always the best solution. If your applet is suffering from flicker, try 
overriding update and drawing only portions of the screen first; that may solve your problem. 
D ouble-buffering is less efficient than regular buffering, and also takes up more memory and 
space, so if you can avoid it, make an effort to do so. In terms of nearly eliminating animation 
flicker, however, double-buffering works exceptionally well. 


Creating Applets with D ouble-B uffering 


To execute double buffering, you need two things: an image to draw on and agraphics context 
for that image. T hosetwo together mimic theeffect of the applet’s drawing surface: the graphics 
context (an instance of Graphics) to provide the drawing methods, such as drawImage and 
drawString, and the Image to hold the dots that get drawn. 


T herearefour major steosto adding double bufferingto your applet. First, your offscreen image 
and graphics context need to be stored in instance variables so that you can pass them to the 
paint() method. D eclare the following instance variables in your class definition: 

Image offscreenImage; 

Graphics offscreenGraphics; 

Second, during the initialization of the applet, you'll createan Image and a Graphics object and 
assign them to these variables (you haveto wait until initialization so you Know how big they're 
going to be). ThecreateImage method gives you an instance of Image, which you can then send 
the getGraphics() Method in order to get anew graphics context for that image 
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offscreenImage = createImage(this.size().width, 
this.size().height) ; 
offscreenGraphics = offscreenImage.getGraphics() ; 


N ow, whenever you have to draw to the screen (usually in your paint method), rather than 
drawingto paint’sgraphics, draw to theoffscreen graphics. For example, to draw an image called 
img at position 10,10, usethisline: 


offscreenGraphics.drawImage(img,10,10,this) ; 


Finally, at the end of your paint method, after all the drawing to the offscreen image is done, 
add the following line to print the offscreen buffer to the real screen: 


g.drawImage(offscreenImage, @, @, this); 


Of course, you most likely will want to overrideupdate so that it doesn’t clear thescreen between 
paintings: 


public void update(Graphics g) { 
paint(g); 


Let's review those four steps: 


Add instance variables to hold the image and graphics contexts for the offscreen 
buffer. 


Create an image and a graphics context when your applet is initialized. 
Do all your applet painting to the offscreen buffer, not the applet’s drawing surface. 
At the end of your paint method, draw the offscreen buffer to the real screen. 


An Example: Checkers Revisited 


Yesterday’s example featured the animated moving red oval to demonstrate animation flicker 
and how to reduceit. Even with the operations you did yesterday, however, theC heckers applet 
ctill flashed occasionally. Let’s revise that applet to include double-buffering. 


First, add the instance variables for the offscreen image and its graphics context: 


Image offscreenImg; 
Graphics offscreenG; 


Second, add an init method to initialize the offscreen buffer: 


public void init() { 
offscreenImg = createImage(this.size().width, 
this.size().height) ; 
offscreenG = offscreenImg.getGraphics() ; 


} 
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Third, modify the paint method to draw to the offscreen buffer instead of to the main graphics 
buffer: 


public void paint(Graphics g) { 
// Draw background 
offscreenG.setColor(Color.black) ; 
offscreenG. fillRect(0,0,100,100); 
offscreenG.setColor(Color.white) ; 
offscreenG. fillRect(100,0,100,100); 


// Draw checker 
offscreenG.setColor(Color.red) ; 
offscreenG. fillOval(xpos,5,90,90) ; 


g.drawImage(offscreenImg,0,0,this) ; 
} 
N ote that you’re still clipping the main graphics rectangle in the update method, as you did 
yesterday; you don’t have to change that part. T he only part that is relevant is that final paint 
method wherein everything is drawn offscreen before finally being displayed. 


Summary 
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T hreemajor topicswerethefocusof today’slesson. First, you learned about usingimagesin your 
applets— locating them, loading them, and using thedrawImage method to display them, either 
at their normal size or scaled to different sizes. Y ou also learned how to create animations using 
images. 


Secondly, you learned how to use sounds, which can beincluded in your applets any time you 
need then— at specific moments, or as background soundsthat can berepeated whiletheapplet 
executes. You learned how to locate, load, and play sounds both using the piay() and the 
getAudioClip() methods. 


Finally, you learned about double-buffering, atechniquethat enables you virtually to diminate 
flicker in animations, at some expense of animation efficiency and speed. U sing images and 
graphics contexts, you can create an offscreen buffer to draw to, the result of which is then 
displayed to the screen at the last possible moment. 


Q&A 


In the Neko program, you put the image loading into the init) method. It 
seems to me that it might take J ava a long time to load all those images, and 
because init) isn’t in the main thread of the applet, there’s going to bea 
distinct pause there. Why not put the image loading at the beginning of the run() 
method instead? 


T here are sneaky things going on behind the scenes. The getImage method doesn’t 
actually load the image in fact, it returns an Image object almost instantaneously, so it 
isn’t taking up alarge amount of processing time during initialization. The image data 
that getImage points to isn’t actually loaded until the image is needed. T his way, J ava 
doesn’t have to keep enormous images around in memory if the program is going to 
use only a small piece. Instead, it can just keep a reference to that data and retrieve 
what it needs later. 


| wrote an applet to do a background sound using the getaudioc1ip() and 1o0p() 
methods. T he sounds works great, but it won’t stop. I’ve tried suspending the 
current thread and killing, but the sound goes on. 


| mentioned this as a small notein the section on sounds; background sounds don’t 
run in the main thread of the applet, so if you stop the thread, the sound keeps going. 
Thesolution is easy— in the same method where you stop the thread, also stop the 
sound, like this: 


runner.stop() //stop the thread 
bgsound.stop() //also stop the sound 


If | use double-buffering, do | still have to clip to a small region of the screen? 
Because double-buffering eliminates flicker, it seems easier to draw the whole 
frame every time. 

Easier, yes, but less efficient. Drawing only part of the screen not only reduces flicker, 
it also limits the amount of work your applet has to do in the paint() method. The 
faster the paint() method works, the faster and smoother your animation will run. 

U sing clip regions and drawing only what is necessary is a good practice to follow in 
general— not just if you have a problem with flicker. 
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Java events are part of the)ava AWT (Abstract W indowing T oolkit) package. An event is the 
way that the AWT communicates to you, as the programmer, and to other Java AWT 
components that something has happened. T hat something can be input from the user (mouse 
movements or clicks, keypresses), changes in the system environment (a window opening or 
closing, the window being scrolled up or down), or a host of other things that might, in some 
way, be interesting to the operation of the program. 


Note: J ava’s Abstract W indowing T oolkit is a package of classes that implements 
most common UI! components, such as windows, buttons, menus, and so on. It is 
also specifically the AWT, and not Java, that generates and manages events. 


In other words, whenever just about anything happens to aJavaAWT component, including 
an applet, an event isgenerated. Someeventsarehandled by theAWT or by the browser without 
your needing to do anything. paint() methods, for example, are generated and handled by the 
browser— all you have to do istell the AWT what you want painted when it gets to your part 
of the window. Some events, however— for example, a mouse click inside the boundaries of 
your applet— you may need to know about. Writing your J ava programs to handlethese kinds 
of events enables you to get input from theuser and have your applet change its behavior based 
on that input. 


Today, you'll learn about managing simple events, including the following basics: 


"| Mouse clicks 

(| Mouse movements, including mouse dragging 

"| Keyboard actions 
You'll also learn about the handleEvent() method, which is the basis for collecting, handling, 
and passing on events of all kinds from your applet to other UI components in the window or 


in your applet itself. Tomorrow, you'll learn how to combine events with the AWT to createa 
complete interface for your applet. 


Mouse Clicks 


Let's start with the most common event you might be interested in: mouse clicks. M ouse-click 
events occur when your user clicks the mouse somewhere in the body of your applet. You can 
intercept mouse clicks to do very simple things— for example, to toggle the sound on and off 
in your applet, to moveto thenext slidein apresentation, or to clear the screen and start over— 
or you can use mouse clicks in conjunction with mouse movements to perform more complex 
motions inside your applet. 


mouseD own and mouseU p 


When you click the mouse once, the AWT generates two events: a mouseDown event when the 
mouse button is pressed, and a mouseup event when the button is released. W hy two individual 
events for a single mouse action? Because you may want to do different things for the “down” 
and the “up.” For example, look at a pull-down menu. T he mouseDown extends the menu, and 
the mouseup selects an iten (with mouseDrags between— but you'll learn about that one later). 
If you have only one event for both actions (mouseup and MouseDown), you cannot implement 
that sort of user interaction. 


H andling mouse events in your applet is easy— all you haveto do is override the right method 
definition in your applet. T hat method will be called when that particular event occurs. H ere’s 
an example of the method signature for a mouseDown event: 


public boolean mouseDown(Event evt, int x, int y) { 


T hemouseDown() method (and themouseup() method as well) takes three parameters: the event 
itself and the x and y coordinates where the mouseDown Or mouseUp event occurred. 


The event argument is an instance of the class event. All system events generate an instance of 
theevent class, which containsinformation about whereand when theevent took place, thekind 
of event it is, and other information that you might want to know about this event. Sometimes 
having ahandle to that event object is useful, as you'll discover later on in this section. 


The x and the y coordinates of the event, as passed in through the x and y arguments, are 
particularly niceto know becauseyou can usethem to determineprecisely wherethemouseclick 
took place. 


For example, here’s a simple method that prints out information about a mouseDown when it 
occurs: 
public boolean mouseDown(Event evt, int x, int y) { 

System.out.println("Mouse down at "+x + "," + y); 

return true; 
} 
By including this method in your applet, every time your user clicks the mouse inside your 
applet, this message will get printed. 


N ote that this method, unlike the other systen methods you've studied this far, returns a 
boolean valueinstead of not returning anything (void). T his will becomeimportant tomorrow 
when you create user interfaces and then manage input to these interfaces; having an event 
handler return true Or false determines whether agiven UI component can intercept an event 
or whether it needs to pass it on to the enclosing component. T he general rule is that if your 
method dealswith theevent, it should return true, which for thefocus of today’slesson isalmost 
always the case. 
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T he second half of the mouse click is the mouseup() method, which is called when the mouse 
button is released. To handle a mouseup event, add the mouseup() method to your applet. 
mouseUp() looks just like mouseDown(): 


public boolean mouseUp(Event evt, int x, int y) { 


} 


An Example: Spots 


In thissection, you'll createan example of an applet that uses mouse events— mouseDown events 
in particular. TheSpotsapplet starts with ablank screen and then sitsand waits. W hen you click 
themouseon that screen, abluedot isdrawn. You can placeup to ten dotson thescreen. Figure 
12.1 shows the Spots applet. 


Figure 12.1. 
T he Spots applet. 


Let's start from the beginning and build this applet, starting from the initial class definition: 
import java.awt.Graphics; 


import java.awt.Color; 
import java.awt.Event; 


public class Spots extends java.applet.Applet { 


final int MAXSPOTS = 10; 
int xspots[] = new int[MAXSPOTS]; 


int yspots[] = new int[MAXSPOTS]; 
int currspots = 0; 


} 


T his class uses three other awt classes: Graphics, Color, and Event. That last class, Event, needs 
to be imported in any applets that use events. T he class has four instance variables: a constant 
to determine the maximum number of spots that can be drawn, two arrays to store the x and 
y coordinates of the spots that have already been drawn, and an integer to keep track of the 
number of the current spot. 


Note: T his class doesn’t include the implements Runnable words in its definition. 
As you'll see later on as you build this applet, it also doesn’t have a run() method. 
W hy not? Because it doesn’t actually do anything on its own— all it does is wait for 
input and then do stuff when input happens. T here's no need for threads if your 
applet isn’t actively doing something all the time. 


Let's start with the init() method, which has one line, to set the background to white: 


public void init() { 
setBackground(Color.white) ; 


} 
Set the background here, instead of in paint(), because paint() is called repeatedly each time 


anew spot is added. Because you really need to set the background only once, putting it in the 
paint() Method unnecessarily slows down that method. Putting it here is a much better idea. 


The main action of this applet occurs on the mouseDown() method, so let’s add that one now: 


public boolean mouseDown(Event evt, int x, int y) { 
if (currspots < MAXSPOTS) 
addspot (x,y); 

else System.out.println("Too many spots."); 

return true; 
} 
W hen the mouse click occurs, the mouseDown() method tests to see whether there are less than 
ten spots. If so, it calls the addspot () method (which you'll write soon). If not, it just prints an 
error message. Finally, it returns true, because all the event methods have to return a boolean 


value (usually true). 


W hat does addspot() do? It adds the coordinates of the spot to the arrays that store the 
coordinates, increments the currspots variable, and then calls repaint (): 
void addspot(int x,int y) { 


xspots[currspots] 
yspots[currspots] 


x5 
Ys 
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currspots++; 
repaint(); 


You may bewondering why you haveto keep track of all thepast spotsin addition to the current 
spot. The reason is because of repaint ): each time you paint the screen, you have to paint all 
the old spotsin addition to the newest spot. O therwise, each time you painted anew spot, the 
older spots would get erased. N ow, on to the paint() method: 
public void paint(Graphics g) { 

g.setColor(Color.blue) ; 

for (int i = 0; i < currspots; i++) { 

g.fi110val(xspots[i] -10, yspots[i] -10,20,20); 
} 
} 

Inside paint, you just loop through the spots you've stored in the xspots and yspots arrays, 
painting each one (actually, painting them alittle to the right and upward so that the spot is 
painted around the mouse pointer rather than below and to the right). 


T hat’s it! T hat’s all you need to create an applet that handles mouse clicks. Everything else is 
handled for you. You have to add the appropriate behavior to mouseDown() OF mouseUp() to 
intercept and handle that event. Listing 12.1 shows the full text for the Spots applet. 


Type Listing 12.1. The Spots applet. 


222 


1: import java.awt.Graphics; 

2: import java.awt.Color; 

3: import java.awt.Event; 

4: 

5: public class Spots extends java.applet.Applet { 
6: 

7: final int MAXSPOTS = 10; 

8: int xspots[] = new int[MAXSPOTS]; 

9: int yspots[] = new int[MAXSPOTS]; 

10: int currspots = @; 

11: 

12: public void init() { 

13: setBackground(Color.white) ; 

14: } 

15: 

16: public boolean mouseDown(Event evt, int x, int y) { 
17: if (currspots < MAXSPOTS) 

18: addspot(x,y); 

19: else System.out.printin("Too many spots."); 
20: return true; 
21: } 
22: 
23: void addspot(int x,int y) { 
24: xspots[Currspots] = x; 
25: yspots[currspots] = y; 
26: currspotst+; 
27: repaint(); 


28: } 


30: public void paint(Graphics g) { 

31: g.setColor(Color.blue) ; 

32: for (int i = 0; i < currspots; itt) { 

33: g.fi110val(xspots[i] -10, yspots[i] -10,20,20); 


Mouse Movements 


Every timethemouseis moved asingle pixel in any direction, amousemove event is generated. 
There are two mouse movement events: mouse drags, where the movement occurs with the 
mouse button pressed down, and plain mouse movements, where the mouse button isn’t 
pressed. 


To manage mouse movement events, use the mouseDrag() and mouseMove() methods. 


mouseD rag and mouseM ove 


Th@mouseDrag() and mouseMove() methods, when included in your applet code, intercept and 
handlemousemovement events. T hemousemove() method, for plain mousepointer movements 
without the mouse button pressed, looks much like the mouse-click methods: 


public boolean mouseMove(Event evt, int x, int y) { 


} 


The mouseDrag() method handles mouse movements made with the mouse button pressed 
down (acompletedragging movement consists of AamouseDown event, aseries Of mouseDrag events 
for each pixel the mouse is moved, and a mouseup even when the button is released). The 
mouseDrag() Method looks like this: 


public boolean mouseDrag(Event evt, int x, int y) { 


} 


mouseE nter and mouseE xit 


Finally, there are the mouseEnter() and mouseExit() methods. T hese two methods are called 
when the mouse pointer enters the applet or when it exits the applet. (In case you’re wondering 
why you might need to know this, it’s more useful on components of user interfaces that you 
might put inside an applet. You'll learn more about U! tomorrow). 
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Both mouseEnter() aNd mouseExit() havesimilar signatures— threearguments: the event object 
and the x and y coordinates of the point where the mouse entered or exited the applet. 


public boolean mouseEnter(Event evt, int x, int y) { 
} 
public boolean mouseExit(Event evt, int x, int y) { 


} 


An Example: Drawing Lines 


Examplesalwayshelp to makeconceptsmoreconcrete. In thissection you'll createan applet that 
enables you to draw straight lineson thescreen by dragging from thestartpoint to theendpoint. 
Figure 12.2 shows the applet at work. 


Figure 12.2. 
Drawing Lines. 


Aswith the Spots applet (on which this applet is based), let’s start with the basic definition and 
work our way through it. Listing 12.2 shows the top of the Lines applet. 


Type Listing 12.2. The top of the Lines applet. 


1: import java.awt.Graphics; 
2: import java.awt.Color; 
3: import java.awt.Event; 
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4: import java.awt.Point; 

5: 

6: public class Lines extends java.applet.Applet { 

7: 

8: final int MAXLINES = 10; 

9: Point starts[] = new Point[MAXLINES]; // starting points 
10: Point ends[] = new Point[10]; // ending points 
11: Point anchor; // start of current line 
12: Point currentpoint; // current end of line 
13: int currline = @; // number of lines 
14: 

15: public void init() { 

16: setBackground(Color.white) ; 
17: } 

18: 


of individual integer coordinates, thisonekeepstrack of Point objects. Points represent an 
x and ay coordinate, encapsulated in a single object. T o deal with points, you import the 
Point Class (line 4) and set up a bunch of instance variables that hold points: 


| Analyss Compared to Spots, this applet added a few extrathings. U nlike Spots, which keeps track 


The starts array holds points representing the starts of lines already drawn. 
The ends array holds the endpoints of those same lines. 

anchor holds the starting point of the line currently being drawn. 
currentpoint holds the current endpoint of the line currently being drawn. 


currline holds the current number of lines (to make sure you don’t go over 
MAXLINES). 


Finally, the init() method (lines 15 through 17), asin the Spots applet, sets the background 
of the applet to white. 


The three main events this applet deals with are mouseDown(), to set the anchor point for the 
current line, mouseDrag(), to animate the current lineas it’s being drawn, and mouseup(), to set 
the ending point for the new line Given that you haveinstance variables to hold each of these 
values, it’s merely a matter of plugging the right variables into the right methods. H ere’s 
mouseDown(), which sets the anchor point: 
public boolean mouseDown(Event evt, int x, int y) { 

anchor = new Point(x,y); 

return true; 
} 
W hile the mouse is being dragged to draw the line, the applet animates the line being drawn. 
Asyou draw the mouse around, the new line moves with it from the anchor point to thetip of 
the mouse. T he mouseDrag event contains the current point each timethe mouse moves, so use 
that method to keep track of the current point (and to repaint for each movement so the line 
“animates”): 
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public boolean mouseDrag(Event evt, int x, int y) { 

currentpoint = new Point(x,y); 

repaint(); 

return true; 
} 
T henew linedoesn’t get added to thearraysof old linesuntil themousebutton isreleased. H ere’s 
mouseUp(), Which teststo make sure you haven't exceeded themaximum number of lines before 
calling the addline() method (described next): 
public boolean mouseUp(Event evt, int x, int y) { 

if (currline < MAXLINES) 

addline(x,y); 

else System.out.printin("Too many lines."); 

return true; 
} 
T headdiine() method iswherethearrays of lines get updated and wheretheapplet is repainted 
to take the new line into effect: 
void addline(int x,int y) { 

starts[currline] = anchor; 

ends[currline] = new Point(x,y); 

currlinet+; 

currentpoint = null; 

repaint(); 
} 
N ote that in this line you also set currentpoint to nu11. Why? Because the current line in 
process is over. By setting currentpoint to nuli1, you can test for that value in the paint) 
method. 


Painting the applet means drawing all theold lines stored in thestarts and ends arrays, as well 
as drawing the current line in process (whose endpoints are in anchor and currentpoint, 
respectively). To show the animation of the current line, draw it in blue H ere’s the paint) 
method for the Lines applet: 


public void paint(Graphics g) { 


// Draw existing lines 
for (int i = 0; i < currline; i++) { 
g.drawLine(starts[i].x, starts[i].y, 
ends[i].x, ends[i].y); 


} 


// draw current line 
g.setColor(Color.blue) ; 
if (Currentpoint != null) 
g.drawLine(anchor.x,anchor.y, 
currentpoint.x,currentpoint.y) ; 


} 


IN paint, when you’redrawingthecurrent line, you test first to seewhether currentpoint iSnull. 
If itis, the applet isn’t in the middle of drawing aline, so there’sno reason to try drawing aline 
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that doesn’t exist. By testing for currentpoint (and by setting currentpoint to null in the 
addline() method), you can paint only what you need. 


T hat’s it— just 60 lines of code and a few basic methods, and you have a very basic drawing 
application in your W eb browser. Listing 12.3 snhowsthefull text of the Lines applet so that you 
can put the pieces together. 


| 
‘Type Listing 12.3. The Lines applet. 


import java.awt.Graphics; 
import java.awt.Color; 
import java.awt.Event; 
import java.awt.Point; 


public class Lines extends java.applet.Applet { 


final int MAXLINES = ; 
Point starts[] = new Point[MAXLINES]; // starting points 


10: Point ends[] = new Point[10]; // endingpoints 
11: Point anchor; // start of current line 

12: Point currentpoint; // current end of line 

13: int currline = 0; // number of lines 

14: 

15: public void init() { 

16: setBackground(Color.white) ; 

17: } 

18: 

19: public boolean mouseDown(Event evt, int x, int y) { 
20: anchor = new Point(x,y); 

21: return true; 

22: } 

23: 

24: public boolean mouseUp(Event evt, int x, int y) { 
25: if (currline < MAXSPOTS) 

26: addline(x,y); 

27: else System.out.printin("Too many lines."); 
28: return true; 

29: } 

30: 

31: public boolean mouseDrag(Event evt, int x, int y) { 
32: currentpoint = new Point(x,y); 

33: repaint(); 

34: return true; 

35: } 

36: 

37: void addline(int x,int y) { 

38: starts[currline] = anchor; 

39: ends[currline] = new Point(x,y); 

40: currline++; 

41: currentpoint = null; 

42: repaint(); 

43: } 

44: 

45: public void paint(Graphics g) { 
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Listing 12.3. continued 


46: 

47: // Draw existing lines 

48: for (int i = 0; i < currline; i++) { 
49: g.drawLine(starts[i].x, starts[i].y, 
50: ends[i].x, ends[i].y); 

51: } 

52: 

53: // draw current line 

54: g.setColor(Color.blue) ; 

55: if (currentpoint != null) 

56: g.drawLine(anchor.x,anchor.y, 
57: currentpoint.x,currentpoint.y) ; 
58: } 

59: } 


K eyboard E vents 


Keyboard events are generated whenever users press akey on thekeyboard. By using key events, 
you can get hold of the values of the keys they pressed to perform an action or merely to get 
character input from the users of your applet. 


The keyD own Method 


To capture a keyboard event, use the keyDown() method: 


public boolean keyDown(Event evt, int key) { 


} 


The keys generated by keyDown events (and passed into keyDown() aS the key argument) are 
integers representing ASCII character values, which includealphanumevic characters, function 
keys, tabs, returns, and so on. T 0 usethem as characters (for example, to print then), you need 
to cast them to characters: 


currentchar = (char)key; 


H ere’s a simple example of a keyDown() method that does nothing but print the key you just 
typed in both its ASCII and character representation: 


public boolean keyDown(Event evt, int key) { 
System.out.println("ASCII value: " + key); 
System.out.printlin("Character: " + (char)key); 
return true; 


D efault K eys 


The event class provides a set of class variables that refer to several standard nonalphanumeric 
keys, such asthe arrow keys. | f your interface uses thesekeys, you can providemorereadablecode 
by testing for thesenamesin your keyDown() method rather than testing for their numeric values. 
For example, to test whether the up arrow was pressed, you might usethe following snippet of 
code: 


if (key == Event.UP) { 
} 


Because the values these class variables hold are integers, you also can usethe switch statement 
to test for them. 


T able 12.1 shows the standard event class variables for various keys and the actual keys they 
represent. 


Table 12.1. Standard keys defined by the event class. 
Class Variable §Represened K ey 


Event . HOME TheH omekey 
Event .END TheEnd key 

Event . PGUP The Page Up key 
Event .PGDN T he Page D own key 
Event .UP Theup arrow 

Event . DOWN The down arrow 
Event .LEFT The left arrow 

Event .RIGHT The right arrow 


An Example: Entering, Displaying, and 
Moving Characters 


Let’s look at an applet that demonstrates keyboard events. This one enables you to type a 
character, and it displays that character in the center of the applet window. You then can move 
that character around on the screen by using the arrow keys. T yping another character at any 
time changes the character as it’s currently displayed. Figure 12.3 shows an example. 
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Figure 12.3. 
TheK eys applet. 


T his applet isactually less complicated than the previousapplets you've used. T hisonehas only 
threemethods: init(), keyDown(), and paint(). T heinstancevariablesarealso simpler, because 
theonly things you need to keep track of are the x and y positions of the current character and 
the values of that character itself. H ere’s the top of this class definition: 

import java.awt.Graphics; 


import java.awt.Event; 
import java.awt.Font; 


public class Keys extends java.applet.Applet { 


char currkey; 
int currx; 
int curry; 


The init() method is responsible for three things: setting the background color, setting the 
applet’sfont (here, 36 point H elveticabold), and settingthebeginning position for thecharacter 
(the middle of the screen, minus a few points to nudge it up and to the right): 


public void init() { 
currx = (this.size().width / 2) -8; // default 
curry = (this.size().height / 2) -16; 
setBackground(Color.white) ; 
setFont(new Font( "Helvetica" ,Font.BOLD, 36) ); 


Becausethis applet’s behavior is based on keyboard input, thekeyDown() method iswheremost 
of the work of the applet takes place: 
public boolean keyDown(Event evt, int key) { 


switch (key) { 
case Event.DOWN: 


curry += 5; 
break; 

case Event.UP: 
curry -= 5; 
break; 

case Event.LEFT: 
currx -= 5; 
break; 


case Event.RIGHT: 
currx += 5; 
break; 
default: 
currkey = (char)key; 


repaint(); 
return true; 
} 
In the center of the keyDown() applet isa switch statement that tests for different key events. If 
the event isan arrow key, theappropriate changeismadeto thecharacter’s position. If the event 
is any other key, the character itself is changed. T he method finishes up with arepaint() and 
returns true. 


The paint() method here is almost trivial; just display the current character at the current 
position. H owever, notethat when the applet starts up, there’sno initial character and nothing 
to draw, so you have to take that into account. T he currkey variable is initialized to 0, so you 
paint the applet only if currkey has an actual value: 


public void paint(Graphics g) { 
if (currkey != 0) { 
g.drawString (String. valueOf(currkey), currx,curry) ; 
} 
} 


Listing 12.4 shows the complete source for the K eys applet: 
Type 


Listing 12.4. The Keys applet. 
: import java.awt.Graphics; 
: import java.awt.Event; 
import java.awt.Font; 


public class Keys extends java.applet.Applet { 


char currkey; 
int currx; 


ONO RWN 


continues 
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Listing 12.4. continued 


9: int curry; 

10: 

11: public void init() { 

12: currx = (this.size().width / 2) -8; // default 
13: curry = (this.size().height / 2) -16; 
14: 

15: setBackground(Color.white) ; 

16: setFont(new Font( "Helvetica" ,Font.BOLD,36) ); 
17: } 

18: 

19: public boolean keyDown(Event evt, int key) { 
20: switch (key) { 

21: case Event.DOWN: 

22: curry += 5; 

23: break; 

24: case Event.UP: 

25: curry -= 5; 

26: break; 

27: case Event.LEFT: 

28: currx <= 5) 

29: break; 

30: case Event.RIGHT: 

31: currx += 5) 

32: break; 

33: default: 

34: currkey = (char)key; 

35: } 

36: 

37: repaint(); 

38: return true; 

39: } 

40: 

41: public void paint(Graphics g) { 

42: if (currkey != 0) { 

43: g.drawString(String.valueOf(currkey), currx,curry) ; 
44: } 

45: } 

46: } 


Testing for Modifier K eys 


Shift, control, and meta aremodifier keys. T hey don’t generatekey eventsthemselves, but when 
you get an ordinary mouse or keyboard event, you can test to see whether those keys were held 
down when the event occurred. Sometimes it may be obvious— shifted alphanumeric keys 
produce different key events than unshifted ones, for example. For other events, however— 
mouse events in particular— you may want to handle an event with amodifier key held down 
differently from a regular version of that event. 
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T heevent class providesthree methods for testing whether or not a modifier key isheld down: 
shiftDown(), metaDown(), and controlDown(). All return boolean values based on whether that 
modifier key isindeed held down. You can usethesethreemethodsin any of the event handling 
methods (mouse or keyboard) by calling them on the event object passed into that method: 
public boolean mouseDown(Event evt, int x, int y ) { 

if (evt.shiftDown) 


// handle shift-click 
else // handle regular click 


The AWT Event Handler 


T hedefault methods you’velearned about today for handling basic eventsin applets are actually 
called by a generic event handler method called handleEvent(). T h@ handleEvent() method is 
how theAWT generically deals with events that occur between application components and 
events based on user input. 


In the default handleEvent() method, basic events are processed and the methods you learned 
about today are called. T o handleevents other than thosementioned here, to changethedefault 
event handling behavior, or to create and pass around your own events, you need to override 
handleEvent in your own Java programs. T he handleEvent() method looks like this: 


public boolean handleEvent(Event evt) { 


} 


To test for specific events, examinethelD instance variable of theevent object that gets passed 
in. Theevent |D isan integer, but fortunately, theevent class defines a whole set of event IDs 
as class variablesthat you can test for in thebody of thenandieEvent. Becausethese class variables 
are integer constants, a switch statement works particularly well. For example, here's a simple 
handleEvent() method to print out debugging information about mouse events: 


public boolean handleEvent(Event evt) { 
switch (evt.id) { 
case Event.MOUSE_DOWN: 
System.out.println("MouseDown: " + 
evt.x + "," + evt.y); 
return true; 
case Event.MOUSE_UP: 
System.out.println("MouseUp: " + 
evt.x + "," + evt.y); 
return true; 
case Event.MOUSE_MOVE: 
System.out.println("MouseMove: " + 
evt.x + "," + evt.y); 
return true; 
case Event.MOUSE_DRAG: 
System.out.println("MouseDown: " + 
evt.x + "," + evt.y); 
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return true; 
default: 
return false; 
} 
} 


You can test for the following keyboard events: 


(| Event.KEYPRESS iS generated when a key is pressed (the same as the keyDown() 
method). 

Event . KEYRELEASE IS generated when a key is released. 

Event.KEYACTION iS generated when a Key action (a press and a release) occurs. 


You can test for these mouse events: 


Event .MOUSE_DowN iS generated when the mouse button is pressed (the same as the 

mouseDown() method). 

|] Event.moUSE_uP is generated when the mouse button is released (the same as the 
mouseUp() method). 

(] Event.MOUSE_MOovE iS generated when the mouse is moved (the same as the mouseMove() 
method). 

"| Event.MOUSE_DRAG iS generated when the mouse is moved with the button pressed (the 
same as the mouseDrag() Method). 

(] Event.MOUSE_ENTER iS generated when the mouse enters the applet (or acomponent of 
that applet). You can also use the mouseEnter() method. 

(| Event .MOUSE_EXIT is generated when the mouse exits the applet. You can also use the 

mouseExit() method. 


In addition to these events, the Event class has a whole suite of methods for handling UI 
components. You'll learn more about these events tomorrow. 


N ote that if you override handieEvent() in your class, none of the default event handling 
methods you learned about today will get called unless you explicitly call then in the body of 
handleEvent(), SO be careful if you decide to do this. O ne way to get around this is to test for 
the event you're interested in, and if that event isn’t it, to call super. handleEvent() so that the 
superclass that defines handieEvent() Can process things. H ere’s an example of how to do this: 


public boolean handleEvent(Event evt) { 
if (evt.id == Event.MOUSE_ DOWN) { 
// process the mouse down 
return true; 
} else { 
return super.handleEvent(evt) ; 


} 


Summary 


H andling eventsin J ava’sA bstract W indowingT oolkit (AW T ) iseasy. M ost of thetime, all you 
need to do isstick theright method in your applet code, and your applet intercepts and handles 
that method. H ere are some of the basic events you can manage in this way: 


M ouse clicks— mouseUp() and mouseDown() methods for each part of a mouse click. 


M ouse movements— mouseMove() and mouseDrag() for Mouse Movement with the 
mouse button released and pressed, respectively, as well aS mouseEnter() and 
mouseExit() for when the mouse enters and exits the applet area. 


keyDown for when a key on the keyboard is pressed. 


All eventsin theAWT generatean Event object; insidethat object, you can find out information 
about the event, when it occurred, and itsx and y coordinates (if applicable). You can also test 
that event to see whether a modifier key was pressed when the event occurred, by using the 
shiftDown(), controlDown(), aNd metaDown() methods. 


Finally, there is the handieEvent(), the “parent” of the individual event methods. The 
handleEvent() method is actually what the Java system calls to manage events, the default 
implementation callsthe individual method events where necessary. T o override how methods 
are managed in your applet, override hand1eEvent. 


Q&A 


Q In the Spots applet, the spot coordinates are stored in arrays, which havea 
limited size. H ow can | modify this applet so that it will drawn an unlimited 
number of spots? 


A You can do one of a couple things: 


The first thing to do is test, in your addspot() method, whether the number of spots 
has exceeded maxspots. T hen create a bigger array, copy the dements of the old array 
into that bigger array (use the system. arraycopy() Method to do that), and reassign 
the x and y arrays to that new, bigger array. 


The second thing to do isto use the vector class. vector, part of the java.util package, 
implements an array that is automatically growable— sort of like a linked list isin 
other languages. T he disadvantage of vector is that to put something into vector, it 
has to be an actual object. T his means you'll have to cast integers to Integer objects, 
and then extract their values from Integer objects to treat them as integers again. The 
vector Class enables you to add and remove objects to the end of vector just as you 
can in an array (by using method calls, rather than array syntax). Check it out. 
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mouseDown() aNd mouseUp() seem to apply to only a single mouse button. H ow can 
| determine which button on the mouse has been pressed? 


At the moment, you can’t. AWT assumes that you’re using only one mouse button, or 
if you have amouse with multiple buttons, that you’re using only the left one 
Although this provides some limitations on the kinds of actions you can perform in 
your applet, it does provide a cross-platform solution. Renenber— different systens 
have different mice, so writing your applet to do something specific with the right 
mouse button isn’t a good idea if the people running your applet are using 

M acintoshes and have only one mouse button. If you really want to have different 
mouse actions perform different things, test for modifier keysin your mouseDown() and 
mouseUp() methods. 


W hat’s a meta key? 


It's popular in U nix systems, and often mapped to Alt on most keyboards. Because 
Shift and Ctrl are much more popular and widespread, it’s probably a good idea to 
base your interfaces on those modifier keys if you can. 


H ow do I test to see whether the Return key has been pressed? 


Return (line feed) is character 10; Enter (carriage return) is character 13. N ote that 
different platforms may send different keys for the actual key marked Return. In 
particular, Unix systems send line feeds, M acintoshes send carriage returns, and DOS 
systems send both. So, to provide a cross-platform behavior, you may want to test for 
both line feed and carriage return. 


The word from the] ava team is that a Return is a Return is a Return regardless of the 
platform. H owever, at the time of this writing, it is questionable whether or not this is 
currently true in the] ava developer’s kit. You may want to check the API documenta 
tion for the Event class to see whether this has changed in the interim. 


| looked at the API for the Event class, and there are many more event types 
listed there than the ones you mention today. 


Yes. The Event class defines many different kinds of events, both for general user 
input, such as the mouse and keyboard events you learned about here, and also events 
for managing changes to the state of user interface components, such as windows and 
scroll bars. Tomorrow, you'll learn about those other events. 
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For thepast five days you’veconcentrated on creating appletsthat do very simplethings: display 
text, play an animation or asound, or enable very basic interactions with the user. O nce you get 
past that point, however, you may want to start creating more complex applets that behavelike 
real applications, enbedded in aW eb page— applets that start to look likereal GU applications 
with buttons, menus, text fields and other dements of a real application. 


It's this sort of real work in Java applets and applications that J ava’s Abstract W indowing 
Toolkit, or AW T , wasdesigned for. You’veactually been usingtheAWT all along, asyou might 
have guessed from the classes you've been importing. T heappiet class and most of the classes 
you've been using this week are all integral parts of the AWT. In fact, the H ot] ava browser is 
also written in Java and uses the AWT as well. 


TheAWT provides the following: 

[| A full set of UI widgets and other components, including windows, menus, buttons, 
checkboxes, text fields, scrollbars, and scrolling lists 

[| Support for UI “containers,” which can contain other enbedded containers or U| 
widgets 

[| An event system for managing system and user events between and among parts of the 
AWT 


[| Mechanisms for laying out components in a way that enables platform-independent 
UI design 


T oday, you'll learn about how to useall thesethingsin your J avaapplets. T omorrow, you'll learn 
about creating windows, menus, and dialogs, which enable you to pop up separate windows 
from the browser window. In addition, you can usethe AWT in stand-alone applications, so 
everything you'velearned so far this week can still beused. If you find theframework of theW eb 
browser too limiting, you can take your AWT background and start writing full-fledged J ava 
applications. 


T oday, however, you'll continue focusing on applets. 


Note: T his is by far the most complex lesson so far. T here’s alot to cover and alot 
of code to go through today, so if it starts becoming overwhelming, you might 
want to take two days (or more) for this one 


An AWT Overview 


T he basic idea behind the AWT is that aJ ava window is a set of nested components, starting 
from theoutermost window all the way down to the smallest UI component. C omponents can 


includethings you can actually seeon thescreen, such aswindows, menubars, buttons, and text 
fields, and they can also includecontainers, which in turn can contain other components. Figure 
13.1 shows how a sample page in aJ ava browser might include several different components, 


all of which are managed through the AWT. 


T his nesting of components within containers within other components creates a hierarchy of 
components, from the smallest checkbox inside an applet to the overall window on the screen. 
The hierarchy of components determines the arrangement of items on the screen and inside 
other items, theorderin which they arepainted, and how events arepassed from onecomponent 


to another. 


Figure 13.1. Window 
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T hese are the major components you can work with in the AWT: 


More 
panels 


Text field 


Label 


Containers. Containers are gnneric AWT components that can contain other compo- 


nents, including other containers. The most common form of container is the panel, 
which represents a container that can be displayed on screen. Applets are a form of 


panel (in fact, the appiet class is a subclass of the panei Class). 


Canvass. A canvas is a simple drawing surface. Although you can draw on panels (as 


you've been doing all along), canvases are good for painting images or other graphics 


operations. 


fields, and other typical elements of a user interface. 


Ul components. T hese can include buttons, lists, simple popup menus, checkboxes, test 
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(| Window construction components T hese include windows, frames, menubars, and 
dialogs. T hese are listed separately from the other UI components because you'll use 
these less often— particularly in applets. In applets, the browser provides the main 
window and menubar, so you don’t have to use these. Your applet may create a new 
window, however, or you may want to write your own Java application that uses these 
components. 


T heclassesinsidethej ava. awt packagearewritten and organized to mirror theabstract structure 
of containers, components, and individual UI components. Figure 13.2 showssomeof theclass 
hierarchy that makesup themain classesin theAW T .T heroot of most of theAW T components 
is the class component, which provides basic display and event handling features. T he classes 
Container, Canvas, TextComponent, and many of the other UI components inherit from 
Component. Inheriting from the container Class are objects that can contain othe AWT 
components— the panel and window classes, in particular. N ote that the java.applet.Applet 
class, even though it livesin its own package, inherits from Pane1, So your applets arean integral 
part of the hierarchy of componentsin the AWT system. 


A partial AWT dass 
hierarchy. 


TextField 


A graphical user interface-based application that you writeby using theAWT can beascomplex 
as you like, with dozens of nested containers and components inside each other. AWT was 
designed so that each component can play its part in the overall AW T system without needing 
to duplicate or keep track of the behavior of other parts in the system. 


The Basic User Interface Components 


Thesimplest form of AW T component isthebasic U | component. You can createand add these 
to your applet without needing to know anything about creating containers or panels— your 
applet, even before you start painting and drawing and handling events, is already an AWT 
container. Because an applet isa container, you can put other AWT components— such as U | 
components or other containers— into it. 
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In thissection, you'll learn about the basic UI! components: labels, buttons, checkboxes, choice 
menus, and text fields. In each case, the procedurefor creating thecomponent isthesame— you 
first createthecomponent, and then add itto thepane that holdsit, at which pointitisdisplayed 
on thescreen. T o add acomponent to apandi (such as your applet, for example), use the ada() 
method: 
public void init() { 

Button b = new Button("OK"); 

add(b); 
} 
N otethat wherethecomponent appearsin the panel dependson thelayout that pane isdefined 
to have. T he default layout for panels such as appletsisFiowLayout, with acentered alignment, 
which meansthat components are added from left to right in rows, and then row by row asthey 
fit, with each row centered. T his explains why some of the examplesin this section look alittle 
funny. You'll learn more about panels and layouts in the next section. 


N otealso that each of these componentshasan action associated with it— thatis, somethingthat 
component does when it’s activated. Actions generally trigger events or other activitiesin your 
applet (often called callbacksin other window toolkits). In thissection, you'll focus on creating 
the components themselves; you'll learn about adding actions to them later in today’s lesson. 


On to the components! 


Labels 


Thesimplest form of UI component is the label. 


NEWee Labdsare, effectively, text strings that you can use to label other UI components. 
TERM 


T headvantagesthat alabel hasover an ordinary text stringisthat it followsthelayout of thegiven 
panel, and you don’t haveto worry about repainting it every time the panel is redrawn. Labels 
also can be easily aligned within apandi, enabling you to attach labels to other UI components 
without knowing exact pixel positions. 


To create a label, use one of the following constructors: 


Label() creates an empty label, with its text aligned left. 
Label(String) creates a label with the given text string, also aligned left. 


Label(String, int) createsa label with the given text string and the given alignment. 
T he available alignments are stored in class variables in Labe1, making them easier to 
remember: Label.RIGHT, Label.LEFT, and Label. CENTER. 


The label's font is determined by the overall font for the component (as set by the setFont() 
method). 
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H ere’s some simple code to create a few labels. Figure 13.3 shows how this looks on screen: 


add(new Label("aligned left ")); 
add(new Label("aligned center", Label.CENTER) ); 
add(new Label(" aligned right", Label.RIGHT) ) ; 


Figure 13.3. 
Labels. aligned lett 


aligned center 


aligned right 


Once you havea label object, you can use methods defined in the Labe1 Classto get and set the 
values of the text as shown in T able 13.1. 


Table 13.1. Label methods. 


Method Action 

getText () Returns a string containing this label’s text 

setText (String) Changes the text of this label 

getAlignment () Returns an integer representing the alignment of this label’: 


@ iS Label.LEFT, 1 1S Label.CENTER, 2 iS Label. RIGHT 


setAlignment(int) | Changesthe alignment of this label to the given integer or class 
variable 


B uttons 
The second user interface component to explore is the button. 


NEWe- Buttonsaresimple UI components that trigger some action in your interface when they 
TERM are pressed. For example, a calculator applet might have buttons for each number and 
operator, or a dialog box might have buttons for “OK” and “Cancel.” 


To create a button, use one of the following constructors: 


Button() Creates an empty button with no label. 
Button(String) creates a button with the given string object as a label. 


Once you have a button object, you can get the value of the button’s label by using the 
getLabe1() method and set the label using the setLabel (String) methods. 


Figure 13.4 shows some simple buttons, created using the following code: 
add(new Button("Rewind") ) ; 
add(new Button("Play")); 


add(new Button("Fast Forward")); 
add(new Button("Stop")); 


Figure 13.4. 


Buttons Rewind | Play | Fast Forward | Stop | 


Checkboxes 
Checkboxes can be selected or deselected to provide options. 


NEWe Checkboxesare user interface components that havetwo states: on and off (or checked and 

TERM unchecked, selected and unselected, trueand false, and so on). U nlikebuttons, checkboxes 
usually don’t trigger direct actionsin aU! but, instead, are used to indicate optional features of 
some other action. 


Checkboxes can be used in two ways: 


N onexclusive, meaning that given a series of checkboxes, any of then can be selected. 
Exclusive, meaning that within one series, only one checkbox can be selected at a time 


T helatter kind of checkboxes are called radio buttons or checkbox groups, and are described in 
the next section. 


N onexclusive checkboxes can becreated by using the checkbox class. You can create a checkbox 
by using one of the following constructors: 


Checkbox() creates an empty checkbox, unselected. 

Checkbox (String) creates a checkbox with the given string as a label. 

Checkbox(String, null, boolean) creates a checkbox that is either selected or 
unselected based on whether the boolean argument is true Or false, respectively. (The 


null is used as a placeholder for a group argument. O nly radio buttons have groups, as 
you'll learn in the next section). 


Table 13.2 lists the checkbox methods; Figure 13.5 shows a few simple checkboxes (only 
Underwear is selected), generated using the following code: 
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add(new Checkbox(" 
add(new Checkbox(" 
add(new Checkbox(" 
add(new Checkbox (" 
add(new Checkbox(" 


Figure 13.5. 
Checkboxes 
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Shoes")); 
Socks")); 
Pants")); 
Underwear", null, true)); 
Shirt")); 
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” Yellow 
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«4 Orange 
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Table 13.2. Checkbox methods. 


Method 


Action 


getLabel() 


Returns a string containing this checkbox’s label 


setLabel(String) | Changesthe text of the checkbox’s label 


getState() 


Returns true OF false, based on whether the checkbox is selected 
or not 


setState(boolean) | Changesthe checkbox’s state to selected (true) or unselected 


(false) 


Radio Buttons 


Radio buttons are a variation on the checkbox. 


NEWee- Radio buttons have the same appearance as checkboxes, but only one in a series can be 
TERM sdected at atime 


To create a series of 


radio buttons, first create an instance of checkboxGroup: 


CheckboxGroup cbhg = new CheckboxGroup() ; 


Then create and add the individual checkboxes, using the group asthe second argument, and 
whether or not that checkbox is selected (only one in the series can be selected): 


add(new Checkbox("Yes", cbg, true); 
add(new Checkbox("no", cbhg, false); 


H ere’s a Simple example (the results of which are shown in Figure 13.6): 
CheckboxGroup cbg = new CheckboxGroup(); 

add(new Checkbox("Red", cbg, true)); 

add(new Checkbox("Blue", cbhg, false)); 

add(new Checkbox("Yellow", cbhg, false)); 

add(new Checkbox("Green", cbhg, false)); 


add(new Checkbox("Orange", cbg, false)); 
add(new Checkbox("Purple", cbg, false)); 


Figure 13.6. 
Radio buttons ae Red 
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All the checkbox methods defined in the previous section can be used with the checkboxes in 


the group. In addition, you can usethe getcheckboxGroup() and setCheckboxGroup() methods 
to access and change the group of any given checkbox. 


Finally, the getcurrent() and setcurrent (Checkbox) methods, defined in thecheckbox group, 
can be used to get or set the currently selected checkbox. 


Choice Menus 
The choice menu is amore complex UI component than labels, buttons, or checkboxes. 


NEWe Choicemenusare popup (or pulldown) menus that enable you to select an item from that 
TERM manu. Themenu then displays that choice on the screen. 


To create a choice menu, create an instance of the choice class, and then use the adaItem() 
method to add individual items to it in the order in which they should appear: 
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Choice c = new Choice(); 

c.addItem("Apples") ; 

c.addItem("Oranges"); 

c.addItem("Strawberries") ; 

c.addItem("Blueberries") ; 

c.addItem("Bananas"); 

Finally, add the entire choice menu to the panel in the usual way: 
add(c); 


Figure 13.7 shows asimple choice menu generated from code in the previous example: 


Figure 13.7. 
Choice menus. Apples 


Oranges 


Strawberries 


Blueberries 


Baranas 


Tip: Choice menus enable only one selection per menu. If you want to select 
multiple items, use a scrolling list instead. 


Onceyour choice menu is created, regardless of whether it’s added to apanel, you can continue 
to add items to that menu by using the adaztem() method. T able 13.3 shows some other 
methods that may be useful in working with choice menus. 


Table 13.3. Choice menu methods. 


Method Action 

getItem(int) Returns the string item at the given position (items inside a choice 
begin at a, same as arrays) 

countItems () Returns the number of items in the menu 


getSelectedIndex() Returns the index position of the item that’s selected 


M ethod Action 
getSelectedItem() | Returnsthe currently selected item as a string 
select (int) Selects the item at the given position 
select (String) Selects the item with that string 
Text Fields 


Unlike the UI components up to this point, which enable you to select only among several 
options to perform an action, text fields allow you to enter any values. 


NEWee- Tett fidds enable your reader to enter text. 
TERM 


To create a text field, use one of the following constructors: 


|] TextField) creates an empty TextField o characters wide. 

TextField(int) creates an empty text fied with the given width in characters. 
TextField(String) creates a text field o characters wide, initialized with the given 
string. 

TextField(String, int) creates a text fied with the given width in characters and 
containing the given string. If the string is longer than the width, you can select and 
drag portions of the text within the fidd and the box will scroll left or right. 


For example, thefollowinglinecreatesatext field 30 characterswidewith thestring "Enter Your 
Name" aSits initial contents. 


TextField tf = new TextField("Enter Your Name",3Q); 
add(tf); 


Tip: T ext fields include only the editable field itself. You usually need to includea 
label with atext field to indicate what belongs in that text field. 


Note: T ext fields are different from text areas; text fields are limited in size and are 
best used for one line items, whereas text areas have scrollbars and are better for 
larger text windows. Both can be edited and enable selections with the mouse. 
You'll learn about text areas later today. 
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You can also create a text field that obscures the characters typed into it— for example, for 
password fields. To do this, first createthetext fieldsitself, and then usethesetEchoCharacter () 
method to set the character that is echoed on the screen. H ereis an example: 


TextField tf = new TextField(30); 
tf.setEchoCharacter('*'); 


Figure 13.8 shows three text boxes (and labels) that were created by using the following code: 


add(new Label("Enter your Name")); 

add(new TextField("your name here",45)); 
add(new Label("Enter your phone number") ); 
add(new TextField(12) ); 

add(new Label("Enter your password") ); 
TextField t = new TextField(2Q); 
t.setEchoCharacter('*'); 

add(t); 


Figure 13.8. 
Text fidds Enter your Name 


Enter your phone number 


Text fialds inherit from the class Textcomponent and have a whole suite of methods, both 
inherited from that class and defined in its own class, that may be useful to you in your Java 
programs. T able 13.4 shows a selection of those methods. 


Table 13.4. Text field methods. 


Method Action 

getText() Returns the text this text fidd contains (as a string) 

setText (String) Puts the given text string into the field 

getColumns() Returns the width of this text field 

select(int, int) Selects the text between the two integer positions (positions 
start from o) 

selectAll() Selects all the text in the field 
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M ethod Action 


isEditable() Returns true Or false based on whether the text is editable or 
not 

setEditable(boolean) True (the default) enables text to be edited: taise freezes the text 

getEchoChar ( ) Returns the character used for masking input 

echoCharIsSet () Returns true Or false whether the field has a masking character 
or not 


Panels and Layout 


You know at this point that an AWT pand can contain UI components or other panes. T he 
question now is how those components are actually arranged and displayed on the screen. 


In other windowing systems, UI components are often arranged using hard-coded pixel 
measurements— put text field tf at 10,30, for example— the same way you used the graphics 
Operationsto paint squares and ovals on thescreen. In theAWT , thewindow may bedisplayed 
on many different windowing systems on many different screens and with many different kinds 
of fonts with different font metrics. Therefore, you need a more flexible method of arranging 
components on the screen so that a layout that looks nice on one platform isn’t a jumbled 
unusable mess on another. 


For just this purpose, Java has layout managers, insets, and hints that each component can 
provide for helping lay out the screen. 


N otethat thenicething about AWT componentsand user interfaceitemsisthat you don’t have 
to paint then— the AWT system manages all that for you. If you have graphical components 
or images, or you want to create animationsinsidepandis, you still haveto do that by hand, but 
for most of the basic components, all you have to do is put them on the screen and J ava will 
handle the rest. 


Layout Managers 


Theactual appearanceof theAWT componentson the screen is determined by two things: the 
order in which they are added to the panel that holds them, and the layout manager that panel 
is currently using to lay out the screen. T he layout manager determines how portions of the 
screen will be sectioned and how components within that pane! will be placed. 


N ote that each panel on the screen can have its own layout manager. By nesting panels within 
panels, and using the appropriate layout manager for each one, you can often arrange your U | 
to group and arrange components in away that is both functionally useful and also looks good 
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on a variety of platforms and windowing systems. You'll learn about nesting panels in a later 
section. 


The AWT provides four basic layout managers: FlowLayout, GridLayout, BorderLayout, and 
CardLayout. | 0 create alayout manager for agiven panel, usethesetLayout ) method for that 
panel: 
public void init() { 

this.setLayout (new FlowLayout()) ; 
} 
Setting the default layout manager, like defining the user interface components, is best done 
during the applet or class's initialization, which is why it’s included here. 


Once the layout manager is set, you can start adding components to the pana. The order in 
which components are added is often significant, depending on which layout manager is 
currently active. Read on for information about the specific layout managers and how they 
present components within the panel to which they apply. 


The following sections describe the four basic Java AWT layout managers. 


The FlowLayout Class 

T heFlowLayout Classisthe most basic of layouts. U sing the flow layout, components areadded 
to the pane oneat atime, row by row. If acomponent doesn’t fit onto arow, it’s wrapped onto 
the next row. T he flow layout also has an alignment, which determines the alignment of each 
row. By default, each row is aligned centered. Figure 13.9 shows a flow layout at its best— a 
simple row of buttons, centered on aline 


Figure 13.9. 


Flow layout _one | two | three | four five i 
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To create a basic flow layout with a centered alignment, use the following line of codein your 
pandl’s initialization (because this isthe default panelayout, you don’t need to includethisline 
if that is your intent): 


setLayout(new FlowLayout()); 


To create a flow layout with an alignment other than centered, add the FlowLayout.RIGHT OF 
FlowLayout.LEFT Class variable as an argument: 


setLayout (new FlowLayout (FlowLayout.LEFT) ) ; 


You can also set horizontal and vertical gap values by using flow layouts. T hegap isthenumber 
of pixels between components in apane’; by default, the horizontal and vertical gap values are 
three pixels, which can bevery closeindeed. H orizontal gap spreads out componentsto the left 
and to theright, vertical gap to the top and bottom of each component. Add integer arguments 
to theflow layout constructor to increasethegap (alayout gap of 10 pointsin both thehorizontal 
and vertical directions is shown in Figure 13.10): 


setLayout (new FlowLayout(FlowLayout.LEFT) ,10,10); 


Figure 13.10. 


Flow layout with a gap of wone| two] three] four] five | 


10 points 


Grid Layouts 

Grid layouts use a layout that offers more control over the placement of components inside a 
panel. Using agrid layout, you portion off the area of the pandl into rows and columns. Each 
component you then add to the panel is placed in a “cell” of the grid, starting from the top row 
and progressing through each row from left to right (here’s wherethe order of callsto the ada ) 
method are very relevant to how the screen islaid out). By using grid layouts and nested grids, 
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you can often approximate the use of hard-coded pixel values to place your UI components 
precisely where you want them. Figure 13.11 showsa grid layout with three columns and three 


rows. 
Figure 13.11. 
Grid layout. 
one two three 
four five 


T ocreateagrid layout, indicatethenumber of rowsand columnsyou want thegrid to havewhen 
you create a new instance of the gridLayout Class: 


setLayout (new GridLayout(3,3)); 


Grid layoutscan also haveahorizontal and vertical gap between components; to create gaps, add 
those pixel values: 


setLayout(new GridLayout(3,3,10,15)); 
Figure 13.12 shows a grid layout with a 10-pixel horizontal gap and a 15-pixel vertical gap. 


Grid baglayouts, asimplemented by theeridBagLayout Class, arevariationson grid layouts. G rid 
bag layoutsalso enableyou to lay out your user interfaceelementsin arectangular grid, but with 
grid bag layouts you have much morecontrol over the presentation of each element in the grid. 
Grid bag layouts use a helper class, GridBagConstraints, to indicate how each cell in thegrid is 
to be formatted. 


Note: T he GridBagLayout and GridBagConstraints Classes were added to the] ava 
D eveloper’s Kit just before this book went to press. For amuch better description 
of grid bag layouts, see the API documentation for those classes that comes with 
theJDK. 
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Figure 13.12. 
Grid layouts with horizontal 
and vertical gap. 


B order Layouts 

Border layouts behave differently from flow and grid layouts. When you add acomponent to 
a panel that uses a border layout, you indicate its placement as a geographic direction: north, 
south, east, west, and center (see Figure 13.13). The components around all the edges are laid 
out with as much sizeas they need; the component in the center, if any, gets any space left over. 


Figure 13.13. 
Border layout. 


To usea border layout, you create it as you do the other layouts: 


setLayout(new BorderLayout()) ; 
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Then you add the individual components by using a special ada() method: the first argument 
to add() iS a string indicating the position of the component within the layout: 

add("North", new TextField("Title",5Q)); 

add("South", new TextField("Status",5Q) ); 

You can also usethisform of add ) for the other layout managers; the string argument will just 
be ignored if it’s not needed. 


Border layouts can also have horizontal and vertical gaps. N ote that the north and south 
components extend all the way to the edge of the pand,, so the gap will result in less space for 
theeast, right, and center components. T 0 add gapsto aborder layout, includethosepixel values 
as before: 


setLayout (new BorderLayout(10,10)); 


Card Layouts 


Card layoutsare different from the other layouts. U nlikewith theother threelayouts, when you 
add components to a card layout, they arenot all displayed on the screen at once. Card layouts 
areused to produceslideshowsof components, oneat atime. If you’veever used theH yperC ard 
program on the M acintosh, you’ve worked with the same basic idea. 


Generally when you create a card layout, the components you add to it will be other container 
components— usually panes. You can then use different layouts for thoseindividual “cards” so 
that each screen has its own look. 


When you add each “card” to the panel, you can give it aname. Then you can use methods 
defined on the cardLayout class to move back and forth between different cards in the layout. 


For example, here's how to create a card layout containing three cards: 


setLayout(new CardLayout()) ; 
Panel one = new Panel() 
add("first", one); 

Panel two = new Panel() 
add("second", two); 

Panel three = new Panel() 
add("third", three); 
show(this, "second"); 


Insets 


W hereas horizontal gap and vertical gap are used to determine the amount of space between 
componentsin apanel, insets are used to determinetheamount of space around the pane! itself. 
T he insets class provides values for the top, bottom, left, and right insets, which are then used 
when the panel itself is drawn. Figure 13.14 shows an inset in aGridLayout. 


Insets 
Figure 13.14, | | 


Insets, 
one two three 


T oincludean inset, overridethe insets() method in your class (your Appiet class or other class 
that serves as a panel): 
public Insets insets() { 

return new Insets(10,10,10,10); 
} 
T heargumentsto the|nsets constructor provide pixel insets for the top, bottom, left, and right 
edges of the panel. T his particular example provides an inset of 10 pixelson all four sides of the 
panel. 


Handling UI Actions and E vents 


If you stopped reading today’s lesson right now, you could go out and create an applet that had 
lots of little Ul components, nicely laid out on the screen with the proper layout manager, gap, 
and insets. If you did stop right here, however, your applet would be really dull, because none 
of your UI components would actually do anything when they were pressed or typed into or 
selected. 


For your UI componentsto do something when they areactivated, you need to hook up theU |’s 
action with an operation. 


T estingfor an action by aU! component isaform of event managenent— thethingsyou learned 
yesterday about events will come in handy here. In particular, Ul components produce the 
special kind of event called an action. To intercept an action by any UI component, you define 
an action() method in your applet or class: 
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public boolean action(Event evt, Object arg) { 


} 


The action() method should look familiar to the basic mouse and keyboard event methods. 
Likethosemethods, it gets passed the event object that representsthisevent. It also getsan extra 
object, which can be of any type of object. W hat’s that second argument for? 


T hesecond argument to theaction method dependson theU | component that’s generating the 
event. T he basic definition is that it’s any arbitrary argument— when acomponent generates an 
event, it can pass along any extra information that might later be needed. Because that extra 
information may be useful for you, it’s passed on through the action() method. 


All thebasic UI components (except for labels, which haveno action) havedifferent actionsand 
arguments: 


(| Buttons create actions when they are selected, and a button’s argument is the label of 
the button. 

Checkboxes, both exclusive and nonexclusive, generate actions when a box is checked. 
The argument is always true. 

Choice menus generate an action when a menu item is selected, and the argument is 
that item. 

“| Text fields create actions when the user presses R eturn inside that text field. N ote that 
if the user tabs to a different text field or uses the mouse to change the input focus, an 
action is not generated. O nly a Return triggers the action. 


N otethat with actions, unlikewith ordinary events, you can havemany different kindsof objects 
generating the event, as opposed to a single event such aS a mouseDown. TO deal with those 
different UI components and the actions they generate, you have to test for the type of object 
that called the event in the first place inside the body of your action() method. T hat object is 
stored in the event’s target instance variable, and you can usethe instanceof operator to find 
out what kind of UI component sent it: 

public boolean action(Event evt, Object arg) { 

if (evt.target instanceof TextField) 
handleText(evt.target) ; 


else if (evt.target instanceof Choice) 
handleChoice(arg) ; 


- 


Although you can handle U! actions in the body of the action) method, it’s much more 
common simply to defineahandler method and call that method from action() instead. H ere, 
there are two handler methods: one to handle the action on the text field (nandieText()) and 
oneto handlethe action on the choice menu (handlechoice()). Depending on the action you 
want to handle, you may also want to pass on theargument from theaction, theU I component 
that sent it, or any other information that the event might contain. 


H ere’sasimple applet that has five buttons labeled with colors. The action) method tests for 
a button action and then passes off the word to amethod called changecolor(), which changes 
the background color of the applet based on which button was pressed (see Figure 13.15 to see 
the applet in action): 


import java.awt.*; 
public class ButtonActionsTest extends java.applet.Applet { 


public void init() { 
setBackground(Color.white) ; 


add(new Button("Red")); 
add(new Button("Blue")); 
add(new Button("Green")); 
add(new Button("White")); 
add(new Button("Black")); 


} 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof Button) 
changeColor((String)arg) ; 
return true; 


} 


void changeColor(String bname) { 
if (bname.equals("Red")) setBackground(Color.red) ; 
else if (bname.equals("Blue")) setBackground(Color.blue) ; 
else if (bname.equals("Green")) setBackground(Color.green) ; 
else if (bname.equals("White")) setBackground(Color.white) ; 
else setBackground(Color.black) ; 


Figure 13.15. 
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Nesting Panels and Components 


Adding UI components to individual applets is fun, but applets begin to turn into lots of fun 
when you begin working with nested panels. By nesting different pandlsinside your applet, and 
panelsinsidethosepana’s, you can createdifferent layouts for different parts of the overall applet 
area, isolate background and foreground colors and fonts to individual parts of an applet, and 
manage the design of your UI components much more cleanly and simply. T he more complex 
the layout of your applet, the more likely you're going to want to use nested panels. 


Nested Panels 


Panels, as you’ve already learned, are components that can be actually displayed on screen; 
Panel’SSuperclasscontainer providesthegeneric behavior for holding other componentsinside 
it. The Appiet class, which your applets all inherit from, is a subclass of panei. To nest other 
panelsinsidean applet, you merely create anew panel and add it to theapplet, just as you would 
add any other UI component: 

setLayout(new GridLayout(1,2,10,10)); 

Panel panel1 = new Panel(); 

Panel panel2 = new Panel(); 

add(panel1) ; 

add(panel2) ; 

You can then set up an independent layout for those subpanels and add AWT components to 
them (including still more subpanels) by calling the ada() method in the appropriate panel: 
panel1.setLayout(new FlowLayout()); 

panel1.add(new Button("Up")); 

panel1.add(new Button("Down") ); 

Although you can do all thisin asingle class, it’scommon in applets that make heavy use of the 
panels to factor out the layout and behavior of the subpanels into separate classes, and to 
communicate between the panel's by using method calls. You'll look at an extensive example of 
this later on in today’s lesson. 


E vents and Nested Panels 


W hen you create applets with nested panels, those panels form a hierarchy from theoutermost 
panel (theapplet, usually), to theinnermost U! component. T hishierarchy isimportant to how 
each component in an applet interacts with the othe components in the applet or with the 
browser that containsthat applet; in particular, the component hierarchy determines the order 
in which components are painted to the screen. 


M oreimportantly, the hierarchy also affects event handling, particularly for user input events 
such as mouse and keyboard events. 
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Events arereceived by theinnermost component in thecomponent hierarchy and passed up the 
chain to theroot. Suppose, for example, that you havean applet with a subpanel that can handle 
mouse events(usingthemouseDown() and mouseup() methods) and that pane containsa button. 
Clicking on the button means that the button receives the event before the panel does; if the 
button isn’t interested in that mouseDown ), the event gets passed to the pand, which can then 
process it or pass it further up the hierarchy. 


Remember the discussion about the basic event methods yesterday? Y ou learned that the basic 
event methods all return boolean values. T hose boolean values becomeimportant when you’re 
talking about handling events or passing them on. 


An event handling method, whether it is the set of basic event methods or the more generic 
handleEvent(), can do one of three things, given any random event: 


N ot be interested in the event (this is usually true only for handieEvent(), which 
receives all the events generated by the system). If this is the case, the event is passed 
on up the hierarchy until a component processes it (or it isignored altogether). In this 
case, the event handling method should return false. 

Intercept the event, processit, and return true. In this case, the event stops with that 
event method. Recall that this is the case with the basic mouseDown() and keyDown() 
methods that you learned about yesterday. 

Intercept the method, process it, and pass it on to the next event handler. Thisisa 
more unusual case, but you may create a user interface by using nested components 
that will want to do this. In this case, the event method should return false to pass 
the event on to the next handler in the chain. 


More UI Components 


Once you master the basic UI components and how to add them to panels and manage their 
events, you can add moreU! components. In thissection, you'll learn about text areas, scrolling 
lists, scrollbars, and canvases. 


N ote that the UI components in this section do not produce actions, so you can’t use the 
action() method to handle their behavior. Instead, you have to use a generic handleEvent() 
method to test for specific events that these UI components generate. You'll learn more about 
this in the next section. 


Text Areas 


T ext areas are like text fields, except they have more functionality for handling large amounts 
of text. Because text fields are limited in size and don’t scroll, they are better for oneline 
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responses and text entry; text areas can be any given width and height and have scrollbars in 
default, so you can deal with larger amounts of text more easily. 


To create atext area, use one of the following constructors: 


TextArea() creates an empty text area o rows long and o characters wide Given that a 
text area with no dimensions can’t be displayed, you should make sure you change the 
dimensions of this new text area before adding it to a panel (or just use the next 
constructor instead). 


TextArea(int, int) creates an enpty text area with the given rows and columns 
(characters). 


(] TextArea(String) creates atext area displaying the given string, o rows by o columns. 


(] TextArea(String, int, int) creates atext area by displaying the given string and with 
the given dimensions. 


Figure 13.16 shows a simple text area generated from the following code: 


String str = "Once upon a midnight dreary, while I pondered, weak and weary,\n" + 
"Over many a quaint and curious volume of forgotten lore,\n" + 
"While I nodded, nearly napping, suddenly there came a tapping,\n" + 
"As of some one gently rapping, rapping at my chamber door.\n" + 
"\"'Tis some visitor,\" I muttered, \"tapping at my chamber door-\n"; 


add(new TextArea(str,10,60)); 


Figure 13.16. Once upon a midnight dreary, while | pondered, weak and weary, 
A text area. Over many a quaint and curious volume of forgotten lore, 

While | nodded, nearly napping, suddenly there came a tapping, 
4s of some one gently rapping, rapping at my chamber door, 
“Tis some visitor," | muttered, "tapping at my chamber door- 
Only this, and nothing more,” 


Ah, distinctly | remember it was in the bleak December, 
And each separate dying ember wrought its ghost upon the floor, 
Eagerly | wished the morrow ;- vainly | had sought to borrow 


A ee 


Both text areas and text fields inherit from the textcomponent Class, so alot of the behavior for 
text fields (particularly getting and setting text and selections) isusableon text areas as well (refer 
to T able 13.4). T ext areas also have anumber of their own methods that you may find useful. 
T able 13.5 shows a sampling of those methods. 
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Table 13.5. Text area methods. 


M ethod Action 

getColumns() Returns the width of the text area, in characters or 
columns 

getRows () Returns the number of rows in the text area (not the 
number of rows of text that the text area contains) 

insertText (String, int) Inserts the string at the given position in the text (text 


positions start at a) 


replaceText(String, int, int) Replacethe text between the given integer positions 
with the new string 


Scrolling Lists 


Remember the choice menu, which enables you to choose one of several different options? A 
scrolling list isfunctionally similar to achoice menu in that it lets you pick several options from 
alist. Scrolling lists differ in two significant ways: 


Scrolling lists are not popup menus. T hey’re lists of items in which you can choose 
one or more items from a list. If the number of items is larger than the list box, a 
scrollbar is automatically provided so that you can see the other items. 


A scrolling list can be defined to accept only one item at a time (exclusive), or multiple 
items (nonexclusive). 


To create a scrolling list, create an instance of the List class and then add individual items to 
that list. The List class has two constructors: 


List() creates an empty scrolling list that enables only one selection at atime 


List(int, boolean) creates a scrolling list with the given number of visible lines on 
the screen (you’re unlimited as to the number of actual items you can add to the list). 
The boolean argument indicates whether this list enables multiple selections (true) or 
not (false). 


After creating aList object, add items to it using the addttem() method and then add thelist 
itself to the panel that contains it. H eve’s an example, the result of which is shown in Figure 
13.17: 


List lst = new List(5, true); 


1st.addItem("Hamlet") ; 
1st.addItem("Claudius") ; 


261 


1lst.addItem(" 
lst.addItem(" 
1lst.addItem(" 
1lst.addItem(" 
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add(lst); 


Figure 13.17. 
A scrolling lig. 


Gertrude"); 
Polonius"); 
Horatio"); 
Laertes"); 
Ophelia"); 


The Java Abstract Windowing T oolkit 


Harrilet f 
Claudius | 
Horatio. == SSO 

i 


T able 13.6 shows some of the methods available to scrolling lists. Seethe API documentation 
for a complete set. 


Table 13.6. Scrolling list methods. 


Method Action 
getItem(int) Returns the string item at the given position 
countItems() Returns the number of items in the menu 


getSelectedIndex() 


getSelectedIndexes() 


getSelectedItem() 


getSelectedItems() 


select(int 


) 


select (String) 


Returns the index position of the item that’s selected (used for 
lists that enable only single selections) 


Returns an array of index positions (used for lists that enable 
multiple selections) 


Returns the currently selected item as a string 

Returns an array of strings containing all the selected items 
Selects the item at the given position 

Selects the item with that string 


Scrollbars and Sliders 


T ext areas and scrolling lists come with their own scrollbars, which are built into those U| 
components and enable you to manage both the body of the area or the list and its scrollbar as 
asingleunit. You can also createindividual scrollbars, or sliders, to manipulatea range of values. 
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Scrollbars are used to select a value between a maximum and aminimum value. T o changethe 
current value of that scrollbar, you can use three different parts of the scrollbar (see Figure 
13.18): 


Arrows on either end, which increment or decrement the values by some small unit (1 
by default). 


A rangein the middle, which increnents or decrements the value by a larger amount 
(10 by default). 


A box in the middle, often called an devator or thumb, whose position snows where in 
the range of values the current value is located. M oving this box with the mouse 
Causes an absolute change in the value, based on the position of the box within the 
scrollbar. 


Figure 13.18. 


Scrollbar parts Airowee) 


Box (elevator, thumb) 


Range (+10) 


Choosing any of these visual elements causes a change in the scrollbar’s value; you don’t have 
to update anything or handle any events. All you haveto do isgivethe scrollbar amaximum and 
minimum, and J ava will handle the rest. 


To create a scrollbar, you can use one of three constructors: 


Scrollbar() creates a scrollbar with 0, @ asitsinitial maximum and initial minimum 
values, in a vertical orientation. 

Scrollbar (int) creates a scrollbar with @, o asits initial maximum and initial mini- 
mum values. The argument represents an orientation, for which you can use the class 
variables Scrollbar .HORIZONTAL and Scrollbar.VERTICAL. 

L] Scrollbar(int, int, int, int, int) creates a scrollbar with the following arguments 
(each one is an integer, and must be presented in this order): 

The first argument is the orientation of the scrollbar: scrollbar .HORIZONTAL and 
Scrollbar. VERTICAL. 
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The second argument is the initial value of the scrollbar, which should bea value 
between the scrollbar’s maximum and minimum values. 


Thethird argument is the the overall width (or height, depending on the orientation) 
of the scrollbar’s box. In user interface design, a larger box implies that a larger 
amount of the total range is currently showing (applies best to things such as windows 
and text areas). 


The fourth and fifth arguments are the minimum and maximum values for the 
scrollbar. 


H ere’sasimpleexampleof ascrollbar thatincrementsasinglevalue(seeFigure13.19). T helabel 
to the left of the scrollbar is updated each time the scrollbar’s value changes: 


import java.awt.*; 


public class SliderTest extends java.applet.Applet { 
Label 1; 


public void init() { 

1 = new Label("0"); 

add(1); 

add(new Scrollbar(Scrollbar.HORIZONTAL, 1, 0, 1, 100)); 
t 


public boolean handleEvent(Event evt) { 
if (evt.target instanceof Scrollbar) { 
int v = ((Scrollbar)evt.target) .getValue() ; 
1.setText (String.valueOf(v)) ; 
} 


return true; 


} 


Figure 13.19. 
A scrollbar. 0 =Jj = 


The scrollbar class provides several methods for managing the values within scrollbars (see 
Table 13.7). 


Table 13.7. Scrollbar methods. 


M ethod Action 
getMaximum() Returns the maximum value 
getMinimum( ) Returns the minimum value 


M ethod Action 


getOrientation() Returns the orientation of this scrollbar: 
o for vertical, 1 for horizontal 


getValue() Returns the scrollbar’s current value 
setValue(int) Sets the current value of the scrollbar 
Canvases 


Although you can draw on most AWT components, such as panels, canvases do little except let 
you draw on them. T hey can’t contain other components, but they can accept events, and you 
can create animations and display images on them. C anvases, in other words, should be used for 
much of the stuff you learned about earlier this week. 


NEWe- A canvasisa component that you can draw on. 
TERM 


To createacanvas, usethe canvas Classand add it to apanel as you would any other component: 


Canvas can = new Canvas(); 
add(can) ; 


More UI Events 


Yesterday, you learned about some basic event types that are generated from user input to the 
mouseor thekeyboard. T heseevent types are stored in theevent object asthe event 1D, and can 
be tested for in the body of a handieEvent() Method by using class variables defined in Event. 
For many basic events, such aS mouseDown() and keyDown(), you can define methods for those 
eventsto handletheevent directly. You learned asimilar mechanism today for U! actions where 
creating an action() method handled a specific action generated by aU! component. 


T hemost general way of managing events, however, continuesto bethehand1eEvent() method. 
For events relating to scrollbars and scrolling lists, the only way to intercept these events is to 
override handleEvent(). 


To intercept a specific event, test for that event’s ID. The available 1D s are defined as class 
variables in the Event class, So you can test them by name. You learned about some of the basic 
events yesterday; Table 13.8 shows additonal events that may be useful to you for the 
components you've learned about today (or that you might find useful in general). 
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Table 13.8. Additional events. 


Event ID W hat It Represents 

ACTION_EVENT Generated when aU! component action occurs 
KEY_ACTION Generated when text field action occurs 
LIST_DESELECT Generated when an item in a scrolling list is deselected 
LIST_SELECT Generated when an item in a scrolling list is selected 


SCROLL_ABSOLUTE Generated when ascrollbar’s box has been moved 


SCROLL_LINE_DowN Generated when ascrollbar’s bottom endpoint (or left endpoint) is 
selected 


SCROLL_LINE_UP Generated when ascrollbar’s top endpoint (or right endpoint) is 
selected 


SCROLL_PAGE_DowN Generated when the scrollbar’s field below (or to the left of) the 
box is selected 


SCROLL_PAGE_UP Generated when the scrollbar’s field above (or to the right of) the 
box is selected 


A Complete E xample: 
RGB to HSB Converter 


Let's take a break here from theory and smaller examples to create a larger, more complex 
example that puts together much of what you've learned so far. T he following applet example 
demonstrates layouts, nesting panels, creating user interface components, and catching and 
handling actions, as well as using multiple classes to put together a single applet. In short, it’s 
probably the most complex applet you'll create so far. 


Figure 13.20 showsthe applet you'll be creating in this example T heC olorT est applet enables 
you to pick colors based on RGB (red, green, and blue) and HSB (hue, saturation, and 
brightness) values. 


Figure 13.20. 
TheColorT et applet. red | 12% Hue 
Green Saturation 
Blue | 12% Brightness 
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TheColorT est applet has three main parts: acolored box on the left side and two groups of text 
fields on the right. T he first group indicates RGB values, the right, H SB. By changing any of 
the valuesin any of the text boxes, the colored box is updated to thenew color, as are the values 
in the other group of text boxes. 


T his applet uses two classes: 


Colortest, which inherits from Applet. T his is the controlling class for the applet 
itself. 


ColorControls, which inherits from panei. You'll create this class to represent a group 
of three text fields and to handle actions from those text fields. T wo instances of this 
class, one for the RGB values and one for the H SB ones, will be created and added to 
the applet. 


Let's work through thisstep by step, becauseit’s very complicated and can get confusing. All the 
code for this applet will be shown at the end of this section. 


Create the Applet Layout 


T hebest way to start creating an applet that usesAW T componentsisto worry about thelayout 
first and then worry about thefunctionality. W hen dealing with thelayout, you also should start 
with the outermost panel first and work inward. 


M akingasketch of your U1 design can help you figureout how to organizethepanelsinsideyour 
applet or window to best take advantage of layout and space. Figure 13.21 showstheC olorT est 
applet with a grid drawn over it so that you can get an idea of how the panel's and embedded 
panels work. 


Figure 13.21. 
TheColorT et applet pands 
and components. 


Create the Panel Layout 


Let's start with the outermost panel— the applet itself. T his panel has three parts: the color box 
on the left, the RGB text fields in the middle, and theH SB fields on the right. 


Because thisisthe applet, your colortest class will bethe applet class and inherit from Applet. 
You'll also import the AWT classes here (note that because you use so many of them in this 
program, it’s easiest to just import the entire package): 
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import java.awt.*; 
public class ColorTest extends java.applet.Applet { 


} 
Let’sstart with the init) method, whereall thebasic initialization and layout takesplace. T here 
are four major steps: 
1. Set the layout for the big parts of the panel. Although a flow layout would work, a 
grid layout with one row and three columns is a much better idea. 


2. Create the three components of this applet: a canvas for the color box and two 
subpanels for the text fields. 


3. Add those components to the applet. 
4. Finally, initialize the default color and update all the pane's to reflect that default 
color. 


Before you do any of that, let’s set up instance variables to hold the three major components of 
thisapplet. You need to keep hold of theseobjectsso you can updatethingswhen avaluechanges. 


Thecolor box is easy— it’s just a canvas. Call it swatch. 
Canvas swatch; 


N ow onto the subpanels. T here are two of them, and although they have different labels and 
values, they're essentially thesame panel. Y ou could just createcodefor each onehere, but you'd 
end up duplicating a lot of the same code. This is a perfect opportunity, therefore, to create 
another class to represent the subpanels with the text fields on them. Call them colorcontrols 
(you'll get around to creating the class later) and define two variables, raBcontrols and 
HSBcontrols, to hold them: 


ColorControls RGBcontrols, HSBcontrols; 


Back to the init() method. Step oneisthelayout. Let’suseagrid layout and a gap of ten points 
to separate each of the components: 

setLayout (new GridLayout(1,3,10,10)); 

Step two iscreating the components, thecanvasfirst. You havean instance variableto hold that 
one: 


swatch = new Canvas(); 


You need to createtwo instancesof your as-of-yet nonexistentcolorcontrols panelshereas well, 
but you don’t know exactly what you need to create them yet, so let’s put in some basic 
constructors and fill in the details later: 


RGBcontrols 
HSBcontrols 


new ColorControls() 
new ColorControls(); 


Step three is adding them to the pand.. 


add(swatch) ; 
add(RGBcontrols) ; 
add(HSBcontrols) ; 


W hile you're working on layout, add an inset just for fun— ten points along all the edges: 


public Insets insets() { 

return new Insets(10,10,10,10); 
} 
Got it so far? Now you have a skeleton init() method and an insets() method in your 
ColorTest Class. Let’smoveon now to creatingthesubpanel layout— to creatingthatcolorcontrols 
Class. 


D efine the Subpanels 


The colorcontrois class will have behavior for laying out and handling the subpane's that 
represent the RGB and H SB values for the color. colorcontrois doesn’t need to be a subclass 
of Applet because it isn’t actually an applet, it’s just a pand. Define it to inherit from Panel: 


class ColorControls extends Panel { 


} 


Note: You can put the colorcontrois Class in the same file as the colortest class. 
You haven’t been doing this so far because the applets and applications you’ve been 
creating had only one class. If you remember way back to D ay 1, however, you 
learned that you can have multiple class definitions in a single file as long as only 
one of those definitions is declared public. In this case, the colortest Classis 
public (it’s an applet, so it has to be), but the colorcontrois class doesn’t need to 
be, so everything works out fine. 


You need a coupleof instance variables in this class. T he first thing you need isahook back up 
to the applet class that contains this panel. W hy? T he applet class is the class that oversees how 
thesubcomponentswork, so it’sgoing to betheclass that updateseverything. Eventually, you’re 
going to haveto call amethod in that classto indicate that something in this panel has changed. 
Without an actual reference to that outer class, there’s no way to do this. So, instance variable 
number oneis a reference to the class colortest: 


ColorTest outerparent; 


If you figure that the applet class is the one that’s going to be updating everything, that class is 
going to need a way to get hold of the pieces inside this class. In particular, it’s going to be 
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interested in the individual text fields, so you’re going to need instance variables to hold those. 
This creates three of them: 


TextField f1, f2, f3; 


N ow for the constructor for this class. Again, thisisn’t an applet, so you don’t use init(); all 
you need is a constructor method. 


W hat do you need inside that constructor? Y ou need to set the layout for the subpand, create 
the text fields, and add them to the pana. The goal here is to make the colorcontrols Class 
generic enough so that you can useit for both the RGB fields and theH SB fields. 


T hetwo different panels differ in two respects: the labels for thetext fidds, and theinitial values 
for the text fields. T hat’s six values to get before you can create the object. You can pass those 
six valuesin through theconstructorsin colortest. You also need one more. Because you need 
that hook back to the applet class, you should also passin a reference to that object as part of 
the constructor. 


You now haveseven arguments to the basic constructor for thecolorcontrois Class. H ere’sthe 
signature for that constructor: 
ColorControls(ColorTest target, 

String 11, String 12, String 13, 

int vi, int v2, int v3) { 


} 
Given those arguments, you can assign the right values to your instance variables: 
outerparent = target; 

fi 


f2 
f3 


new TextField(String.valueOf(v1),10); 
new TextField(String.valueOf (v2) ,10); 
new TextField(String.valueOf (v3) ,10); 


N otethat becausethe first argument to thetextFie1d constructor isastring, and the valuesthat 
you passed in were integers, you haveto use the valueot() class method (defined in string) to 
convert the integer to a string before creating each text field. 


N ext, you create the layout for this panel. You also use agrid layout for these subpaneis, as you 
did for the applet panel, but this timethegrid will havethree rows (onefor each of thetext fied 
and label pairs) and two columns (one for the labels and one for the fields). 


Given the 3-by-2 grid, you can now add the text fields and labels to that panei. N ote that by 
separating the labels and the text fields into separate cellsin the grid, you can align the labeds, 
creating a nice aligned layout. 

add(new Label(11, Label.RIGHT)); 

add(f1); 


add(new Label(12, Label.RIGHT)); 
add(f2) ; 


add(new Label(13, Label.RIGHT) ); 

add(f3); 

Finally (because | like insets), you'll inset the contents of the subpaned a bit— only on the top 
and bottom edges— by including an insets() method: 


public Insets insets() { 
return new Insets(10,10,0,0); 


} 
You're almost there. You have 98 percent of the layout in place and ready to go, but you're 
missing two things: creating thecolorcontro1s objectsin colortest, and initializing everything 
so that all the components have the right values. 


For both, you need to go back to the colortest class and the init() method you defined there. 
Let’sstart with theinitialization part, becausethat’seasy. T hedefault colorisblack. Set up alocal 
variable to hold that color object: 


Color theColor = new Color(Q,0,0); 
To set the initial color of the color box, all you need to do is set its background: 
swatch.setBackground(theColor) ; 


N ow, let’s finally tackle initializing those subpane’s. The constructor for colorcontrols has 
seven arguments: the colorTest object, three labels (strings), and threeinitial values for thetext 
fields (integers). Let’s do the RGB controls first, because you can easily extract the initial red, 
green, and blue values out of the color object: 
RGBcontrols = new ColorControls(this, "Red", "Green", "Blue", 

theColor.getRed(), theColor.getGreen(), 

theColor.getBlue()); 
Things get complicated on the H SB side of the pana. The coior class provides you with a 
method to get the H SB values out of a color object, but there are two problems: 


The reBtoksB() method is a single class method that insists on returning an array of 
the three values. 


TheH SB values are measured in floating-point values. | prefer to think of H SB as 
integers, wherein the hue is a degree value around a color wheel (@ through 360), and 
saturation and brightness are percentages from @ to 100. H aving H SB as integer values 
also enables you to have a generic subpane,, as was the intent. 


Initializing the H SB subpanel is going to be alittle difficult. 


First, let’s extract those H SB values. Given that the method takes three RGB arguments— an 
array of three floats— and returns an array of three floats, you have to go through this process 
to get those values: 


float[] HSB = Color.RGBtoHSB(theColor.getRed() , 
theColor.getGreen(), theColor.getBlue(),(new float[3])); 
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N ow you have an array of floats, whereHsB/ 0] isthe hue, HsB(1] isthe saturation, and HsB[2] 
isthe brightness. You can now (finally!) initializethe H SB side of the applet, making sure that 
when you pass those H SB valuesinto thesubpand, you multiply them by the right values (360 
for the hues, 100 for the saturation and the brightness) and convert them to integers: 
HSBcontrols = new ColorControls(this, 

"Hue", "Saturation", "Brightness", 

(int) (HSB[@] * 360), (int) (HSB[1] * 100), 

(int) (HSB[2] * 100)); 
Ready to give up? F ear not— you’vedonethehard part. From here, it’s (mostly) easy. O nce you 
have your layout working, you can compile your J ava program and see how it looks. N one of 
your UI components actually does anything, but perfecting the layout is half the battle 


H andle the Actions 


After creating the layout, you set up actions with the UI components so that when the user 
interacts with the applet, the applet can respond. 


T heaction of thisapplet occurs when theuser changesavaluein any of thetext fields. By causing 
an action in atext field, the color changes, thecolor box updatesto thenew color, and the values 
of the fields in the opposite subpanel change to reflect the new color. 


Thecolortest classis responsible for actually doing the updating, because it keeps track of all 
the subpanels. You should be tracking and intercepting events in the subpanel in which they 
occur, however. Becausetheaction of the applet is an actual text action, you can usean action() 
method to intercept it: 
public boolean action(Event evt, Object arg) { 

if (evt.target instanceof TextField) { 


this.outerparent.update(this) ; 
return true; 


else return false; 
} 
In the action() method, you test to make sure the action was indeed generated by a text fidd 
(because there are only text fields available, that’sthe only action you'll get, but it’s a good idea 
to test for it anyhow). If so, call theupdate() method, defined in colortest, to updatetheapplet 
to reflect all the new values. Because the outer applet is responsible for doing all the updating, 
thisis precisely why you need that hook back to the applet— so you can call the right method 
at the right time. 


U pdate the Result 


T heonly part left now isto updateall thevalues and thecolor swatch if oneof thevalues changes. 
For this, you define the update() method in the colorTest Class. T hiS update() method takes 
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a single argument— the colorcontrols instance that contains the changed value (you get that 
argument from the action() method in the subpane)). 


Note: W on’t this update) method interfere with the system’s update() method? 
N ope. Remember, methods can have the same names, but different signatures and 
definitions. Because this update() has a single argument of type colorcontrols, it 
doesn’t interfere with the other version of update(). 


The update() method is responsible for updating all the panels in the applet. T o know which 
panel to update, you need to know which panel changed. You can find out by testing to see 
whether the argument you got passed is the same as the subpanels you have stored in the 
RGBcontrols and HsBcontrols instance variables: 


void update(ColorControls in) { 


if (in == RGBcontrols) { // the change was in RGB 


else { // change was in HSB 
} 
T histest isthe heart of theupdate() method. Let’sstart with that first case— anumber hasbeen 
changed in the RGB text fields. So now, based on thosenew RGB values, you have to generate 
anew color object and update the values on the H SB panel. T o reducesometyping, you create 
a few local variables to hold some basic values. In particular, the values of the text fields are 
strings, and you get into them by accessing thetext field instancevariablesfor thecolorcontrols 
panel (+1, £2, #3) and then usingthegetText () method to extract theactual values. Extract those 
values and store them in string variables so that you don’t have to keep typing: 
String v1 = in.f1.getText(); 
String v2 = in.f2.getText(); 
String v3 = in.f3.getText(); 
Given those string values for RGB, you now create a color object by converting those stringsto 
integers: 
Color c; 


c = new Color(Integer.parseInt(v1),Integer.parseInt(v2), 
Integer.parseInt(v3) ); 


Note: T his part of the example isn’t very robust; it assumes that the user has indeed 
entered real numbers into the text fields. A better version of this would test to make 
sure that no parsing errors had occurred (1 was trying to keep this example small). 
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When you have a color object, you can update the color swatch: 
swatch.setBackground(c) ; 


The next step is to update the H SB panel to the new H SB values. Doing this in the init() 
method isno fun at all, and it’seven lessfun here. T o do this, you call rast oHss to get thefloating- 
point values, convert them to integers with the right values, convert them to strings, and then 
put them back into the text fields for the H SB subpand.. Got all that? H ere’s the code 
float[] HSB = Color.RGBtoHSB(c.getRed(),c.getGreen(), 

c.getBlue(), (new float[3])); 
HSB[@] *= 360; 
HSB[1] *= 100; 
HSB[2] *= 100; 
HSBcontrols.f1.setText (String. valueOf ((int)HSB[Q@])); 
HSBcontrols.f2.setText (String. valueOf ((int)HSB[1])); 
HSBcontrols.f3.setText (String. valueOf ((int)HSB[2])); 
T hesecond part of the update ) method is called when avalueon theH SB side of the panel is 
changed. T his is the “else” in the if-else that determines what to update, given a change. 
Believe it or not, it’s easier to update RGB values given H SB than it is to do it the other way 
around. First, convert the string valuesfrom theH SB text fieldsto integers by using these lines: 
int f1 = Integer.parseInt(v1); 
int f2 = Integer.parseInt(v2) ; 
int f3 = Integer.parseInt(v3) ; 


T here’sa class method in thecolor class that creates a new color object when given three H SB 
values. The catch is that those values are floats, and they’re not the values you currently have. 
To call getHsBcolor() (that’sthenameof themethod), convert theintegersto floats and divide 
by the right amounts: 


c = Color.getHSBColor((float)f1 / 360, (float)f2 / 100, (float)f3/100); 

N ow that you havea color object, the rest is easy. Set the color swatch: 
swatch.setBackground(c) ; 

Then update the RGB text fidds with the new RGB values from the color object: 
RGBcontrols.f1.setText (String. valueOf (c.getRed() ) 


5 
RGBcontrols.f2.setText (String. valueOf(c.getGreen())); 
RGBcontrols.f3.setText (String. valueOf(c.getBlue())); 


The Complete Source Code 


Listing 13.1 shows the complete source code; often it’s easier to figure out what's going on in 
this applet when it’s all in one place and you can follow the method calls and how values are 
passed back and forth. Start with the init¢) method in applet, and go from there 
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Type Listing 13.1. The ColorT est applet. 


import java.awt.*; 


public class ColorTest extends java.applet.Applet { 
ColorControls RGBcontrols, HSBcontrols; 
Canvas swatch; 


public void init() { 
Color theColor = new Color(Q,0,0); 
float[] HSB = Color.RGBtoHSB(theColor.getRed(), 
theColor.getGreen(), theColor.getBlue(), 
(new float[3])); 


setLayout(new GridLayout(1,3,10,10)); 


// The color swatch 
swatch = new Canvas(); 
swatch.setBackground(theColor) ; 


// the control panels 

RGBcontrols = new ColorControls(this, 
"Red", "Green", "Blue", 
theColor.getRed(), theColor.getGreen(), 
theColor.getBlue()); 


HSBcontrols = new ColorControls(this, 
"Hue", "Saturation", "Brightness", 
(int) (HSB[Q@] * 360), (int) (HSB[1] * 100), 
(int) (HSB[2] * 100)); 


add(swatch) ; 


add(RGBcontrols) ; 
add(HSBcontrols) ; 


} 


public Insets insets() { 
return new Insets(10,10,10,10); 


} 

void update(ColorControls in) { 
Color c; 
String v1 = in.f1.getText(); 
String v2 = in.f2.getText(); 


String v3 = in.f3.getText(); 


if (in == RGBcontrols) { // change to RGB 
c = new Color(Integer.parseInt(v1), 
Integer.parseInt(v2), 
Integer.parseInt(v3) ); 
swatch.setBackground(c) ; 


continues 
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Listing 13.1. continued 


float[] HSB = Color.RGBtoHSB(c.getRed(),c.getGreen(), 
c.getBlue(), (new float[3])); 
HSB[@] *= 360; 
HSB[1] *= 100; 
HSB[2] *= 100; 
HSBcontrols.f1.setText (String. valueOf ((int)HSB[Q])); 
HSBcontrols.f2.setText (String. valueOf ((int)HSB[1])); 
HSBcontrols.f3.setText (String. valueOf ((int)HSB[2])); 
} 
else { // change to HSB 
int f1 = Integer.parseInt(v1); 
int f2 = Integer.parseInt(v2); 
int f3 = Integer.parseInt(v3) ; 
c = Color.getHSBColor((float)f1 / 360, 

(float)f2 / 100, (float) 3/100); 
swatch.setBackground(c) ; 
RGBcontrols.f1.setText (String. valueOf(c.getRed())); 
RGBcontrols.f2.setText (String. valueOf ( 

c.getGreen())); 
RGBcontrols.f3.setText (String. valueOf (c.getBlue())); 


class ColorControls extends Panel { 
TextField f1, f2, 3; 
ColorTest outerparent; 


ColorControls(ColorTest target, 
String 11, String 12, String 13, 
int v1, int v2, int v3) { 


this.outerparent = target; 
setLayout(new GridLayout(3,4,10,10)); 


f1 = new TextField(String.valueOf(v1),10); 
f2 = new TextField(String.valueOf (v2) ,10); 
#3 = new TextField(String.valueOf (v3) ,10); 
add(new Label(11, Label.RIGHT) ); 

add(f1); 

add(new Label(12, Label.RIGHT) ); 

add(f2); 

add(new Label(13, Label.RIGHT) ); 

add(f3); 


} 


public Insets insets() { 
return new Insets(10,10,0,0); 


} 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof TextField) { 
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this.outerparent.update(this) ; 
retrue true; 


} 


else return false; 


Summary 


TheJava AWT, or Abstract W indowingT oolkit, is a package of J ava classes and interfaces for 
creating full-fledged access to awindow-based graphical user interfacesystem, with mechanisms 
for graphics display, event management, text and graphics primitives, user interface compo- 
nents, and cross-platform layout. The AWT is used by the H ot] ava browser itself for all its 
functionality. Applets are also an integral part of the AWT toolkit. 


T oday has been a big day; the lesson has brought together everything you’ve learned up to this 
point about simpleapplet management and added alot moreabout creating applets, panels, and 
user interface components and managing the interactions between all of them. With the 
information you got today and the few bits that you'll learn tomorrow, you can create cross- 
platform J ava applications that do just about anything you want. 


Q&A 


Q 


ce) 


You’ve mentioned a lot about the component and container Classes, but it looks 
like the only container objects that ever get created are paneis. What do the 
Component and Container Classes give me? 


T hose classes factor out the behavior for components (generic AW T components) and 
containers (components that can contain other components). Although you don’t 
necessarily create direct instances of these classes, you can create subclasses of them if 
you want to add behavior to the AWT that the default classes do not provide. As with 
most of the J ava classes, any time you need a superclass’s behavior, don’t hesitate to 
extend that class by using your own subclass. 


Can I put aUI component at a specific x and y position on the screen? 


By using the existing layout managers supplied with the AWT toolkit, no. Thisis 
actually a good thing because you don’t know what kind of display environment your 
applet will be run under, what kind of fonts are installed, or what kind of fonts are 
being currently used. By using the layout managers provided with the AWT, you can 
be sure that every portion of your window will be viewable and readable and usable. 
You can’t guarantee that with hard-coded layouts. 
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Q_ | was exploring the AWT package, and I saw this subpackage called peer. There's 


also references to the peer classes sprinkled throughout the API documentation. 
W hat do peers do? 


Peers are responsible for the platform-specific parts of the AWT . For example, when 
you create a]ava AWT window, you have an instance of the window class that provides 
generic W indow behavior, and then you have an instance of windowPeer that creates 
the very specific window for that platform— a motif window under X windows, a 

M acintosh-style window under the M acintosh, or a Windows 95 window under 
Windows 95. T he peers also handle communication between the window system and 
the] ava window itself. By separating the generic component behavior (the AW T 
classes) from the actual system implementation and appearance (the peer classes), you 
can focus on providing behavior in your Java application and let the J ava implementa- 
tion deal with the platform-specific details. 


There's a whole lot of functionality in the AWT that you haven’t talked about 
here. Why? 


Given that even a basic introduction took this long, | figured that if | put in even 
more detail than | already have that this book would turn into T each Y oursdf J ava in 
21 DaysPlusa Few Extra for theAWT Stuff. 


Asit is, |’veleft windows, menus, and dialog until tomorrow, so you'll have to wait 
for those. But you can find out about alot of the other features of AWT merely by 
exploring the API documentation. Start with the appiet class and examine the sorts of 
methods you can call. Then look at panei, from which applet inherits— you have all 
that class's functionality as well. The superclass of Panel iS container, which provides 
still more interesting detail. component comes next. Explore the API and see what you 
can do with it. You might find something interesting. 
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H ereyou areon thelast day of the second week, and you’re just about finished with applets and 
theAWT. With theinformation you'll learn today, you can create a wide variety of applets and 
applications using] ava. N ext week's lessons providemoreof theadvanced stuff that you'll need 
if you start doing really serious work in J ava. 


T oday, to finish up this week, there are three very different topics: 


“| Windows, menus, and dialog boxes— the last of the AWT classes that enable you to 
pop up real windows from applets, and to create stand-alone J ava applications that 
have their own windows 

"| Networking— how to load new HTML files from an applet-capable browser, how to 
retrieve files from W eb sites, and some basics on how to work with generic sockets in 
Java 

"| Extra tidbits— the smaller stuff that didn’t fit in anywhere else, but that might be 
useful to you as you write your J ava applets and applications 


Windows, Menus, and Dialog B oxes 


T oday, you'll finish up thelast bitsof theAWT that didn’t fit into yesterday’slesson. In addition 
to all the graphics, events, UI, and layout mechanisms that the AWT provides, it also provides 
windows, menus, and dialog boxes, enabling to you create fully featured applications either as 
part of your applet or independently for stand-alone ava applications. 


Frames 


The AWT window Class enables you to create windows that are independent of the browser 
window containing the applet— that is, separate popup windows with their own titles, resize 
handles, and menubars. 


T he window class provides basic behavior for windows. M ost commonly, instead of using the 
Window Class, you'll USe window's subclasses, Frame and Dialog. The Frame class enables you to 
create a fully functioning window with amenubar. pialog isamorelimited window for dialog 


boxes. You'll learn more about dialog boxes later on in this section. 
To create a frame, use one of the following constructors: 

new Frame() creates a basic frame without a title. 

new Frame(String) creates a basic frame with the given title 


Framesare containers, just like panels are, so you can add other componentsto them just as you 
would regular panels, using theada() method. T hedefault layout for windowsisBorderLayout: 


win = new Frame("My Cool Window") ; 
win.setLayout(new BorderLayout (10,20) ); 
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win.add("North", new Button("start")); 

win.add("Center", new Button("Move")); 

To set asize for the new window, use the resize() method. To set a location for where the 
window appears, use the move, ) method. N ote that the 1ocation() method can tell you where 
theapplet window ison thescreen so that you can pop up theextrawindow in arelativeposition 
to that window (all thesemethods aredefined for all containers, so you can usethem for applets, 
windows, and the components inside them, subject to the current layout): 
win.resize(10Q0,200) ; 

Dimension d = location(); 

win.move(d.width + 50, d.height + 50); 

When you initially create a window, it’sinvisible. You need to usethe show() method to make 
the window appear on the screen (you can usé hide() to hideit again): 


win.show(); 


Listing 14.1 shows an example of asimple applet with a popup window (both the applet and 
the window are shown in Figure 14.1). The applet has two buttons: one to show the window, 
and one to hide the window. T he window itself, created from a subclass called myFrame has a 
singlelabel: "This is a Window." You'll usethisbasic window and applet all through thissection, 
so the more you understand what’s going on here the easier it will be later. 


‘Type Listing 14.1. A popup window. 


public class GUI extends java.applet.Applet { 
Frame window; 


public void init() { 
add(new Button( "Open Window") ) ; 
add(new Button( "Close Window") ) ; 


window = new MyFrame("A Popup Window") ; 
window.resize(150,150) ; 
window. show() ; 


} 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof Button) { 
String label = (String)arg; 
if (label.equals("Open Window")) { 
if (!window.isShowing() ) 
window. show() ; 


} 
else if (label == "Close Window") { 
if (window. isShowing() ) 
window. hide(); 
} 


return true; 


continues 
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Listing 14.1. continued 


else return false; 


} 

} 

class MyFrame extends Frame { 
Label 1; 


MyFrame(String title) { 
super (title) ; 
setLayout(new GridLayout(1,1)); 
1 = new Label("This is a Window", Label.CENTER) ; 
add(1); 


Figure 14.1. 


Open Window | Close Window | 


Windows, 
| A Popup Windo 
Warning: Applet Window 
This is a Window 
L. | 
Menus 


Each new window you create can have its own menubar along the top of the screen. Each 
menubar can haveanumber of menus, and each menu, in turn, can havemenu items. T heAW T 
provides classes for all these things called, respectively, MenuBar, Menu, and Menultem. 


Menus and Menubars 
To create amenubar for a given window, create a new instance of the class menuBar: 


MenuBar mb = new MenuBar(); 


T o set this menubar as the default menu for the window, use the setmenuBar() method on the 
window: 


window.setMenuBar (mb) ; 


Add individual menus (File, Edit, and so on) to the menubar by creating them and then adding 
them to the menubar: 


Menu m = new Menu("File"); 
mb.add(m) ; 


Somesystems enable you to indicatea special help menu, which may bedrawn on theright side 
of the menubar. You can indicate that a specific menu is the help menu by using the 
setHelpMenu() method. T he given menu should already be added to the menu itself: 


Menu hm = new Menu("Help") ; 
mb.add(hm) ; 
mb.setHelpMenu(hm) ; 


If, for any reason, you want to prevent a user from selecting amenu, you can usethedisable() 
command on that menu (and the enabie() command to make it available again): 


m.disable(); 


Menu Items 
There are four kinds of items you can add to individual menus: 


Instances of the class menuitem, for regular menu items 
Instances of the class checkBoxmenuItem, for toggled menu items 
Other menus, with their own menu items 

Separators, for lines that separate groups of itens on menus 


Regular menu items are added by using themenurtem Class. Add them to amenu using theada( ) 
method: 


Menu m = new Menu("Tools"); 
m.add(new MenuItem("Info")); 
m.add(new MenuItem("Colors")); 
m.add(new MenuItem("Sizes")); 


Submenuscan beadded simply by creating anew instanceof menu and addingit to thefirst menu. 
You can then add items to that menu: 


Menu sb = new Menu("Sizes") ; 
m.add(sb) ; 

sb.add(new MenuItem("Small")); 
sb.add(new MenuItem("Medium") ); 
sb.add(new MenuItem("Large")); 


T hecheckBoxMenuItem Class creates a menu item with a checkbox on it, enabling the menu state 
to betoggled on and off (selecting it once makes the checkbox appear selected; selecting it again 
unselectsthecheckbox). C reateand add acheckbox menu iten thesameway you createand add 
regular menu items: 
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CheckboxMenuItem coords = 
new CheckboxMenuItem("Show Coordinates"); 
m.add(coords) ; 


Finally, to add a separator to amenu (alineused to separate groups of itensin amenu), create 
and add amenu item with the label ".". 

MenuItem msep = new MenuItem("-"); 

m.add(msep) ; 

Any menu item can be disabled by using the disable() method and enabled again using 
enable(). Disabled menu items cannot be selected: 

MenuItem mi = new MenulItem("Fill"); 


m.addItem(mi) ; 
mi.disable(); 


Menu Actions 

The act of selecting amenu item causes an action event to be generated. You can handle that 
action the same way you handle other action methods— by overriding action(). Both regular 
menu itemsand checkbox menu itemshaveactionsthat generatean extra argument representing 
the label for that menu. You can use that label to determine which action to take N ote, also, 
that because checkBoxMenuItem iS a subclass of menuttem, you don’t haveto treat that menu iten 
as a special case: 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof MenuItem) { 
String label = (String)arg; 
if (label.equals("Show Coordinates")) toggleCoords(); 
else if (label.equals("Fill")) fillcurrentArea() ; 
return true; 


else return false; 


An Example 


Let’s add amenu to the window you created in the previous section. Add it to the constructor 
method in the myFrame class (Figure 14.2 shows the resulting menu): 


MyFrame(String title) { 
super (title) ; 
MenuBar mb = new MenuBar(); 
Menu m = new Menu("Colors"); 
m.add(new MenuItem("Red")); 
m.add(new MenuItem("Blue") ); 
m.add(new MenuItem("Green") ); 
m.add(new MenuItem("-")); 
m.add(new CheckboxMenuItem("Reverse Text")); 
mb.add(m) ; 


mb.setHelpMenu(m) ; 
setMenuBar (mb) ; 


= 


Thismenu has four items: one each for the colors red, blue, and green (which, when selected, 
change the background of the window), and one checkbox menu item for reversing the color 
of the text (to white). To handle these menu items, you need an action() method: 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof MenuItem) { 
String label = (String)arg; 
if (label.equals("Red")) setBackground(Color.red) ; 
else if (label.equals("Blue")) setBackground(Color.blue) ; 
else if (label.equals("Green")) setBackground(Color.green) ; 
else if (label.equals("Reverse Text")) { 
if (getForeground() == Color.black) 
setForeground(Color.white) ; 
else setForeground(Color.black) ; 


return true; 


} 


else return false; 


Figure 14.2. 
A menu. 


4 Reverse Text 
Set Text... 


Dialog Boxes 


Dialog boxes are functionally similar to framesin that they pop up new windowson thescreen. 
H owever, dialog boxes are intended to be used for transient windows— for example, windows 
that let you know about warnings, windows that ask you for specific information, and so on. 
Dialogs don’t usually have titlebars or many of the more general features that windows have 
(although you can create one with a titlebar), and they can be made nonresizable or modal. 
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NEWe A modal dialog prevents input to any of the other windows on the screen until that dialog 
TERM isdismissed. 


TheAWT providestwo kinds of dialog boxes: thepialog class, which providesageneric dialog, 
and FileDialog, which produces a platform-specific dialog to choose files to save or open. 


To create a generic dialog, use one of these constructors: 


[| Dialog(Frame, boolean) creates an initially invisible dialog, attached to the current 
frame, which is either modal (true) or not (false). 

(| Dialog(Frame, String, boolean) isthe same as the previous constructor, with the 
addition of atitlebar and a title indicated by the string argument. 


N ote that because you have to give a dialog a Frame argument, you can attach dialogs only to 
windows that already exist independently of the applet itself. 


The dialog window, like the frame window, isa panel on which you can lay out and draw U| 
components and perform graphics operations, just as you would any other panel. Like other 
windows, thedialogisinitially invisible, but you can show it with show, ) and hideit with hide). 


Let's add a dialog to that same example with the popup window. You'll add amenu item for 
changing the text of the window, which brings up the Enter T ext dialog box (see Figure 14.3). 


Figure 14.3. 
The Enter T ext dialog. 


Warning: Applet Window 


[rrisisevindoy 7 
OK | 


dh 


T oadd thisdialog, first add amenu item to that window (theconstructor method for themyFrame 
class) to change the text the popup window displays: 


m.add(new MenuItem("Set Text...")); 


Inthat samemethod, you can createthe dialog and lay out theparts of it (it’sinvisibleby default, 
so you can do whatever you want to it and it won't appear on screen until you show it): 


dl = new Dialog(this, "Enter Text",true) ; 
dl.setLayout(new GridLayout(2,1,30,30)); 
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tf = new TextField(1l.getText() ,20); 
dl.add(tf); 
dl.add(new Button("OK")); 
dl.resize(150,75); 
The action of choosing the menu item you just added brings up the dialog; choosing the O K 
button dismisses it. So you need to add behavior to thisclass’s action method so that the dialog 
works right. To the menu item tests, add aline for the new menu item: 
if (evt.target instanceof MenuItem) { 

if (label.equals("Red")) setBackground(Color.red) ; 

if (label.equals("Blue")) setBackground(Color.blue) ; 

if (label.equals("Green")) setBackground(Color.green) ; 

if (label.equals("Set Text...")) dl.show(); 
} 
Then, because ok is a button, you have to add a special case for that button separate from the 
menu items. In this special case, set the text of the window to the text that was typed into the 
text field, and then hide the dialog again: 
if (evt.target instanceof Button) { 

if (label.equals("OK")) { 


l.setText(tf.getText()); 
dl.hide(); 


File Dialogs 


FileDialog providesa basic file open/save dialog box that enables you to access the file system. 
T heFileDialog Classissystem-independent, but depending on theplatform, thestandard O pen 
File dialog is brought up. 


Note: For applets, you can bring up the file dialog, but due to security restrictions 
you can’t do anything with it (or, if you can, access to any files on the local system 
is severely restricted). FileDialog Is much more useful in stand-alone applications. 


To create a file dialog, use the following constructors: 


FileDialog(Frame, String) creates an Open File dialog, attached to the given frame, 
with the given title. This form creates a dialog to load afile 


FileDialog(Frame, String, int) also creates a file dialog, but that integer argument is 
used to determine whether the dialog is for loading a file or saving a file (the only 
difference is the labels on the buttons; the file dialog does not actually open or save 
anything). T he possible options for the mode argument are FileDialog.Loap and 
FileDialog.SAVE. 
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After you create a FileDialog instance, use show() to display it: 

FileDialog fd = new FileDialog(this, "FileDialog"); 

fd.show(); 

W hen thereader chooses afilein thefile dialog and dismissesit, you can then get to thefilethey 
chose by using the getDirectory() and getFile() methods; both return strings indicating the 
values the reader chose. You can then open that file by using the stream and file handling 
methods (which you'll learn about next week) and then read from or write to that file. 


Window E vents 


Yesterday, you learned about writing your own event handler methods, and you noted that the 
Event Classdefines many standard events for which you can test. W indow events are part of that 
list, So if you use windows, these events may beof interest to you. T able 14.1 showsthoseevents. 


Table 14.1: Window Events from the Event Class. 


WINDOW_DESTROY Generated when a window is destroyed (for example, when the 
browser or applet viewer has quit) 

WINDOW_EXPOSE Generated when the window is brought forward from behind other 
windows 

WINDOW_ICONIFY Generated when the window is iconified 

WINDOW_DEICONIFY Generated when the window is restored from an icon 

WINDOW_MOVED Generated when the window is moved 


Using AWT Windows 
in Stand-Alone Applications 


Because frames are general-purpose mechanisms for creating AW T windows with panels, you 
can use them in your stand-alone J ava applications and easily take advantage of all the applet 
capabilities you learned about thisweek. T 0 do this, write your application asif it were an applet 
(inheriting from theappiet class and using threads, graphics, and U!| componentsas necessary), 
and then add amain() method. H ere’s one for aclass called myawTclass: 
public static void main(String args[]) { 

Frame f = new Frame("My Window"); 

MyAWTClass mac = new MyAWTClass() ; 


mac.init(); 
mac.start(); 


f.add("Center", mac); 
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f.resize(300, 300); 
f.show(); 


} 
This main() method does five things: 


It creates a new frame to hold the applet. 

It creates an instance of the class that defines that method. 

It duplicates the applet environment calls to init() and start(). 

It adds the applet to the frame and resizes the frame to be 300 pixels square. 
It shows the frame on the screen. 


By using this mechanism, you can create a Java program that can function equally well as an 
applet or an application— just include init() for applets and main) for applications. 


If you do create an application that usesthismechanism, be careful of your init() methodsthat 
get parameters from an HT ML file. When you run an applet as an application, you don’t have 
the HTML parameters passed into the init() method. Pass them in as command-line 
arguments, instead, and handlethem in your main() method. T hen set aflag so that the init() 
method doesn’t try to read parameters that don’t exist. 


Networking in] ava 


N etworkingisthecapability of making connectionsfrom your applet or application to asysten 
over the network. N etworking in J ava involves classes in the java.net package, which provide 
cross-platform abstractions for simple networking operations, including connecting and 
retrieving files by using common W eb protocols and creating basic U nix-like sockets. U sed in 
conjunction with input and output streams (which you'll learn much more about next week), 
reading and writing files over the network becomes as easy as reading or writing to files on the 
local disk. 


T herearerestrictions, of course. J ava applets cannot read or writefrom thedisk on themachine 
that’s running them. Depending on the browser, J ava applets may not be able to connect to 
systemsother than theoneupon which they wereoriginally stored. Even given theserestrictions, 
you can still accomplish a great deal and take advantage of the Web to read and process 
information over the net. 


This section describes three ways you can communicate with systems on the net: 


showDocument(), Which enables an applet to tell the browser to load and link to 
another page on the W eb 


openstream(), a method that opens a connection to aURL and enables you to extract 
data from that connection 
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“| The socket classes, socket and serverSocket, which enable you to open standard 
socket connections to hosts and read to and write from those connections 


Creating Links Inside Applets 


Probably the easiest way to use networking inside an applet is to tell the browser running that 
applet to load anew page. You can use this, for example, to create animated image maps that, 
when clicked, load a new page. 


To link to anew page, you create a new instance of the class URL. You saw some of this when 
you worked with images, but let’s go over it alittle more thoroughly here. 


Theurt class represents a uniform resource locator. T 0 createanew URL, you can use one of 
four different forms: 


[| URL(String, String, int, String) createsanew URL object, given a protocol (http, 
ftp, gopher, file), a host name (ww.1ne.com, ftp.netcom.com), a port number (8a for 
http), and a filename or pathname 


(| URL(String, String, String) does the same thing as the previous form, minus the 
port number. 


(| URL(URL, String) creates aU RL, given a base path and a relative path. For the base, 
you Can USE getDocumentBase() for theURL of the current HTML file, or 
getCodeBase for the URL of the] ava class file. T he relative path will be tacked onto 
the last directory in those base U RLs (just like with images and sounds). 


[] urL(String) creates aU RL object from aURL string (which should include the 
protocol, hostname, and filename). 


For that last one(creatingaU RL from astring), you haveto catch amalformed U RL exception, 
so surround the URL constructor with atry...catch: 
String url = "http://www.yahoo.com/"; 
try { theURL = new URL(url); } 
catch ( MalformedURLException e) { 
System.out.println("Bad URL: " + theURL) ; 
} 
Getting aURL object is the hard part. O nce you have one, all you have to do is pass it to the 
browser. Do this by using this single line of code, where theurt isthe U RL object to link to: 


getAppletContext().showDocument(theURL) ; 
T he browser that contains your URL will then load and display the document at that URL. 


Listing 14.2 shows a simple applet that displays three buttons that represent important W eb 
locations (the buttons are shown in Figure 14.4). Clicking on the buttons causes the document 
to be loaded to the locations to which those buttons refer. 


Type Listing 14.2. Bookmark buttons. 


import java.awt.*; 
import java.net.URL; 
import java.net.MalformedURLException; 


public class ButtonLink extends java.applet.Applet { 
Bookmark bmlist[] = new Bookmark[3]; 


public void init() { 
bmlist[®] = new Bookmark("Laura's Home Page", 
"http://www.ine.com/lemay/"); 
bmlist[1] = new Bookmark("Yahoo", 
"http: //www.yahoo.com") ; 
bmlist[2]= new Bookmark("Java Home Page", 
"http://java.sun.com"); 


setLayout(new GridLayout(bmlist.length,1,10,10)); 
for (int i = 0; i < bmlist.length; i++) { 
add(new Button(bmlist[i].name) ); 
} 
} 


public boolean action(Event evt, Object arg) { 
if (evt.target instanceof Button) { 
LinkTo((String)arg) ; 
return true; 
} 
else retrurn false; 


} 


void LinkTo(String name) { 
URL theURL = null; 
for (int i = 0; i < bmlist.length; i++) { 
if (name.equals(bmlist[i].name) ) 
theURL = bmlist[i].url; 
} 
if (theURL != null) 
getAppletContext().showDocument(theURL) ; 


} 


class Bookmark { 
String name; 
URL url; 


Bookmark(String name, String theURL) { 
this.name = name; 
try { this.url = new URL(theURL); } 
catch ( MalformedURLException e) { 
System.out.printlin("Bad URL: " + theURL) ; 
} 
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Figure 14.4. 
Bookmark buttons 


Laura’s Home Page 


Yahoo 


java Home Page 


, ™ Two classes make up this applet: the first implements the actual applet itself, the second 
An V5 is a class representing a bookmark. Bookmarks have two parts: anameand aURL. 


This particular applet creates three bookmark instances and stores them in an array of 
bookmarks (this applet could be easily modified to make bookmarks as parameters from an 
HTML file). For each bookmark, abutton is created whose label is the value of the bookmark’s 
name. 


W hen the buttons are pressed, the 1inkTo() method is called, which tells the browser to load 
the URL referenced by that bookmark. 


O pening Web Connections 


Rather than asking the browser to just load the contents of a file, sometimes you might want to 
get hold of that file’s contents so that your applet can use them. If the file you want to grab is 
stored on theW eb, and can beaccessed using themorecommon URL forms (http, ftp, and so 
on), your applet can use the URL class to get it. 


N ote that for security reasons, applets can connect back only to the same host from which they 
originally loaded. This means that if you have your applets stored on a system called 
www.myhost.com, the only machine your applet can open a connection to will bethat same host 
(and that same host name, so be careful with host aliases). If the filethe applet wants to retrieve 
ison that same system, using URL connections is the easiest way to get it. 
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openStream() 


URL definesamethod called openstream(), which opensanetwork connection using the given 
URL and returns an instance of the class tnputstream (part of the java.io package). If you 
convert that stream to aDataInputStream (with aBufferedInputStream in the middlefor better 
performance), you can then read characters and lines from that stream (you’ll learn all about 
streamson D ay 19). For example, theselinesopen aconnection to theU RL stored in thevariable 
theurL, and then read and echo each line of the file to the standard output: 


try { 
InputStream in = theURL.openStream() ; 
DataInputStream data = new DataInputStream( 
new BufferedInputStream(in) ; 


String line; 
while ((line = data.readLine()) != null) { 
System.out.printin("line") ; 

} 
} 
catch (IOException e) { 

System.out.printin("IO Error: " + e.getMessage()); 
} 


Note: You need to wrap all thoselinesin atry...catch statement to catch 
IOException exceptions. 


H ere’s an example of an applet that uses the openstream() method to open aconnection to a 
W eb site, readsafilefrom that connection (Edgar Allen Poe’spoen “T heRaven”), and displays 
the result in atext area. Listing 14.3 shows the code; Figure 14.5 shows the result after the file 
has been read. 


Type Listing 14.3. The GetRaven class. 


import java.awt.*; 

import java.io.DataInputStream; 

import java.io.BufferedInputStream; 
import java.io. IOException; 

import java.net.URL; 

import java.net.URLConnection; 

import java.net.MalformedURLException; 


public class GetRaven extends java.applet.Applet 
implements Runnable { 


SOONO OA RWN = 


_ 


continues 
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Listing 14.3. continued 


11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 
22: 
23: 
24: 
25: 
26: 
27: 
28: 


URL theURL; 
Thread runner; 
TextArea ta = new TextArea("Getting text...",30,70) ; 


public void init() { 


String url = "http://www.1ne.com/Web/Java/raven.txt"; 

try { this.theURL = new URL(url); } 

catch ( MalformedURLException e) { 
System.out.printin("Bad URL: " + theURL) ; 


} 
add(ta); 
} 


public Insets insets() { 
return new Insets(10,10,10,10); 
} 


public void start() { 
if (runner == null) { 
runner = new Thread(this) ; 
runner.start(); 


} 


public void stop() { 
if (runner != null) { 
runner.stop(); 
runner = null; 


} 


public void run() { 
InputStream conn = null; 
DataInputStream data = null; 
String line; 
StringBuffer buf = new StringBuffer(); 


try { 
conn this.theURL.openStream() ; 
data = new DataInputStream(new BufferedInputStream( 
conn) ); 


while ((line = data.readLine()) != null) { 
buf.append(line + "\n"); 
} 


ta.setText(buf.toString()); 


} 
catch (IOException e) { 
System.out.printin("IO Error:" + e.getMessage()); 


Sams 


Sams.net 
Learning 
Center 


| g 


Figure 14.5. 


The GetRaven class The Raven 
by 
Edgar Allen Poe 


Once upon a midnight dreary, while | pondered, weak and weary, 
Over many a quaint and curious volume of forgotten lore, 

While | nodded, nearly napping, suddenly there came a tapping, 
As of someone gently rapping, rapping at my chamber door, 
"’Tis some visitor,"| muttered, “tapping at my chamber door; 
Only this, and nothing more." 


Ah, distinctly | remember, it was in the bleak December, 
And each separate dying ember wrought its ghost upon the floor, 


Eagerly | wished the morrow; vainly | had sought to borrow 
From my books surcease of sorrow, sorrow for the lost Lenore, 
For the rare and radiant maiden who the angels name Lenore, 
Nameless here forevermore, 


And the silken sad uncertain rustling of each purple curtain 
Thrilled me——-filled me with fantastic terrors never felt before; 
So that now, to still the beating of my heart, | stood repeating, 
“’Tis some visitor entreating entrance at my chamber door, 
Some late visitor entreating entrance at my chamber door, 

This itis, and nothing more," 


Presently my soul grew stronger; hesitating then no longer, 
"sir," said |, "or madam, truly your forgiveness | implore; 

But the factis,| was napping, and so gently you came rapping, 
And so faintly you came tapping, tapping at my chamber door, 


Wuahe | heinit() method (lines 16 to 24) setsup the URL and the text area in which that file 
Analyss will bedisplayed. TheU RL could beeasily passed into theapplet viaan H T M L parameter; 
a here, it’s just hard-coded for simplicity. 


Becauseit might takesome timeto load thefile over thenetwork, you put that routine into its 
own thread and use the familiar start(), stop(), aNd run() methods to control that thread. 


Insiderun() (lines 44 to 64), the work takes place. H ere, you initialize a bunch of variables 
and then open the connection to the URL (using the openstream() method in line51). Once 
the connection is open, you set up an input stream in lines 52 to 56 and read from it, line by 
line, putting the result into an instance of stringButfer (a string buffer is a modifiable string). 


Once all the data has been read, line 59 converts the stringBuffer object into areal string and 
then puts that result in the text area. 


One other thing to note about this example is that the part of the code that opened a network 
connection, read from thefile, and created astringissurrounded by atry and catch statement. 
If any errors occur while you're trying to read or processthefile, these statements enable you to 
recover from them without the entire program crashing (in this case, the program exits with an 
error, because there's little else to be done if the applet can’t read the file). try and catch give 
you the capability of handling and recovering from errors. You'll learn more about exceptions 
on Day 18. 
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The URLconnection Class 


URL’SopenStream() Method isactually asimplified useof theurLconnection Class. URLconnection 
providesaway to retrievefilesby usingU RLS— on W eborFT P sites, for example.urLconnection 
also enables you to create output streams if the protocol allows it. 


To useaURL connection, you first create a new instance of the class uRLconnection, set its 
parameters (whether it enables writing, for example), and then use the connect() method to 
open theconnection. K eep in mind that, with aU RL connection, theclasshandlesthe protocol 
for you based on thefirst part of the U RL, so you don’t haveto makespecific requests to retrieve 
afile all you have to do is read it. 


Sockets 


For networking applications beyond what theurt and urtconnection Classes offer (for example, 
for other protocols or for more general networking applications), J ava provides thesocket and 
ServerSocket Classes as an abstraction of standard socket programming techniques. 


Note: | don’t have the space to give you a full explanation of how socket program- 
ming works. If you haven’t worked with sockets before, see whether openstream() 
will meet your needs. If you really need to do more, any book that discusses socket 
programming will give you the background you need to work with J ava’s sockets. 


T hesocket Classprovidesaclient-sidesocket interfacesimilar to standard U nix sockets. To open 
a connection, create a new instance of socket (where hostname is the host to connect to, and 
portnum is the port number): 


Socket connection = new Socket(hostname, portnum) ; 


Note: If you use sockets in an applet, you are still subject to the security restrictions 
about where you can connect. 


O ncethesocketisopen, you can useinput and output streamsto read and writefrom that socket 
(you'll learn all about input and output streams on D ay 19): 


DataInputStream in = new DataInputStream( 

new BufferedInputStream(connection.getInputStream())); 
DataOutputStream out= new DataOutputStream( 

new BufferedOutputStream(connection.getOutputStream())); 


O nceyou’redonewith thesocket, don’t forget to closeit (thisalso closesall theinput and ouput 
streams you may have set up for that socket): 


connection.close(); 


Server-side sockets work similarly, with the exception of the accept ) method. A server socket 
listens on a TCP port for a connection for a client; when a client connects to that port, the 
accept() method accepts aconnection from that client. By using both client and server sockets, 
you can create applications that communicate with each other over the network. 


To create a server socket and bind it to a port, create a new instance of serverSocket with the 
port number: 


ServerSocket sconnection = new ServerSocket (8888) ; 


To listen on that port (and to accept a connection from any clients if one is made), use the 
accept() method: 


sconnection.accept() ; 


O ncethesocket connection ismade, you can useinput and output streams to read to and write 
from the client. 


See the java.net package for more information about J ava sockets. 


Other Applet Hints 


On this, thelast section of the last day of the second week, let’s finish up with some small hints 
that didn’t fit in anywhere else: using showstatus() to print messages in the browser’ status 
window, providing applet information, and communicating between multiple applets on the 
same page. 


The showStatus Method 


The showstatus() method, available in the applet class, enables you to display a string in the 
status bar of the browser, which contains the applet. You can use this for printing error, link, 
help, or other status messages: 


getAppletContext().showStatus("Change the color"); 


The getAppletContext() method enables your applet to access features of the browser that 
containsit. You already saw a use of this with links, wherein you could use the showDocument () 
method to tell thebrowser to load apage. showstatus() usesthat samemechanism to print status 
messages. 
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Note: showstatus() may not be supported in all browsers, so do not depend on it 
for your applet’s functionality or interface. It is a useful way of communicating 
optional information to your user— if you need amore reliable method of commu- 
nication, set up alabel in your applet and update it to reflect changes in its message. 


Applet Information 


TheAWT gives you amechanism for associating information with your applet. U sually, there 
isamechanism in the browser viewing the applet to view display information. You can usethis 
mechanism to sign your name or your organization to your applet, or to provide contact 
information so that users can get hold of you if they want. 


To provide information about your applet, override the getAppletInfo() method: 


public String getAppletInfo() { 
return "GetRaven copyright 1995 Laura Lemay"; 


Communicating B etween Applets 


Sometimes you want to havean HT M L page that has several different applets on it. T o do this, 
all you haveto do isincludeseveral different iterations of the applet tag— the browser will create 
different instances of your applet for each one that appears on the HT M L page. 


W hat if you want to communicate between those applets? W hat if you want a changein one 
applet to affect the other applets in some way? 


T he best way to do thisisto use the applet context to get to different applets on the same page. 
You've already seen the use of the getappletContext() method for several other uses; you can 
also useit to get hold of the other applets on the page. For example, to call a method in all the 
applets on a page (including the current applet), use the getapplets() method and a for loop 
that looks something like this: 
for (Enumeration e = getAppletContext().getApplets() ; 
e.hasMoreElements();) { 

Applet current = (Applet) (e.nextElement()); 

sendMessage(current) ; 
} 
T he getAppiets() method returns an Enumeration object with alist of the applets on the page. 
Iterating over the Enumeration Object in this way enables you to access each element in the 
Enumeration in turn. 
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If you want to call amethod in aspecific applet, it’s slightly morecomplicated. To do this, you 
give your applets anameand then refer to them by nameinsidethebody of codefor that applet. 


To givean applet aname, use the name parameter in your HTML file 


<P>This applet sends information: 
<APPLET CODE="MyApplet.class" WIDTH=100 HEIGHT=150 

NAME="Sender"> </APPLET> 
<P>This applet receives information from the sender: 
<APPLET CODE="MyApplet.class" WIDTH=100 HEIGHT=150 

NAME="receiver"> </APPLET> 
To get areference to another applet on the same page, use the getApplet() method from the 
applet context with thenameof that applet. T hisgivesyou areferenceto theapplet of that name. 
You can then refer to that applet as if it were just another object: call methods, set its instance 
variables, and so on: 
// get ahold of the receiver applet 
Applet receiver = getAppletContext().getApplet("receiver") ; 
// tell it to update itself. 
reciever.update(text, value) ; 
In this example, you usethe getApplet() method to get areferenceto the applet with thename 
receiver. Given that reference, you can then call methodsin that applet asif it werejust another 
object in your own environment. H ere, for example, if both applets have an update() method, 
you can tell receiver to update itself by using the information the current applet has. 


N aming your applets and then referring to them by using the methods described in this section 
enables your applets to communicate and stay in sync with each other, providing uniform 
behavior for all the applets on your page. 


Summary 


Congratulations! T akeadeep breath— you're finished with W eek 2. T his week has been full of 
useful information about creating applets and using the Java AWT classes to display, draw, 
animate, process input, and create fully fledged interfaces in your applets. 


T oday, you finished exploring applets and the AWT by learning about three concepts. 


First, you learned about windows, frames, menus, and dialogs, which enable you to create a 
framework for your applets— or enable your Java applications to take advantage of applet 
features. 


Second, you head a brief introduction to J ava networking through some of the classes in the 
java.net package. Applet networking includes things as simple as pointing the browser to 
another pagefrom insideyour applet, but can also includeretrievingfilesfrom theW eb by using 
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standard W eb protocols(http, ftp, and so on). For moreadvanced networking capabilities, | ava 
provides basic socket interfaces that can be used to implenent many basic network-oriented 
applets— client-server interactions, chat sessions, and so on. 


Finally, you finished up with the tidbits— small features of the} ava AWT and of applets that 
didn't fit anywhere else, including showstatus(), producing information for your applet, and 
communicating between multiple applets on a single page. 


Q&A 


Q 


A 


po) 


When I create popup windows using the appietviewer, they all show up with this 
big red bar that SayS Warning: applet window. W hat does this mean? 


The warning is to tell you (and the users of your applet) that the window being 
displayed was generated by an applet, and not by the browser itself. T his is a security 
feature to keep an applet programmer from popping up a window that masquerades as 
a browser window and, for example, asks users for their passwords. 


There's nothing you can do to hide or obscure the warning. 


W hat good is having a file dialog box if you can’t read or write files from the 
local file system? 


Applets can’t read or write from the local file system, but because you can use AW T 
components in J ava applications as well as applets, the file dialog box is very useful for 
that purpose. 


H ow can | mimic an HTML form submission in a Java applet? 


Currently, applets make it difficult to do this. T he best (and easiest way) is to use GET 
notation to get the browser to submit the form contents for you. 


HTML forms can be submitted in two ways: by using the cet request, or by using 
post. If you use Get, your form information is encoded in the URL itself, something 
like this: 


http: //www.blah.com/cgi-bin/myscript?foo=1&bar=2&name=Laura 


Because the form input is encoded in the URL, you can write aJava applet to mimic a 
form, get input from the user, and then construct anew URL object with the form 
data included on the end. T hen just pass that URL to the browser by using 
getAppletContext().showDocument(), and the browser will submit the form results 
itself. For simple forms, this is all you need. 


Q Howcan! do post form submissions? 


A You'll have to mimic what a browser does to send forms using post: open a socket to 
the server and send the data, which looks something like this (the exact format is 
determined by the HTTP protocol; this is only a subset of it): 

POST /cgi-bin/mailto.cgi HTTP/1.0 

Content-type: application/x-www-form-urlencoded 

Content-length: 36 

{your encoded form data here} 

If you’ve done it right, you get the CGI form output back from the server. It’s then up 
to your applet to handle that output properly. N ote that if the output isin HTML, 
there really isn’t a way to pass that output to the browser that is running your applet. 
If you get back aU RL, however, you can redirect the browser to that URL. 


Q_ showstatus doesn’t work in my browser. H ow can | give my readers status 
information? 

A Asyou learned in the section on showstatus(), whether or not a browser supports 
showStatus() iS up to that browser. If you must have status-like behavior in your 
applet, consider creating a status label in the applet itself that is updated with the 
information you need to present. 
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® DAY @ 
Modifiers 


Once you begin to program Java for a while, you'll discover that making all your classes, 
methods, and variables public can become quite annoying. T helarger your program becomes, 
and themoreyou reuse your classesfor new projects, themoreyou will want somesort of control 
over their visibility. O ne of the large-scale solutions to this problem, packages, must wait until 
tomorrow, but today you'll explore what you can do within a class. 


T oday, you'll learn how to create and use the following: 


(| Methods and variables that control their access by other classes 
"1 Class variables and methods 


Constant variables, classes that cannot be subclassed, and methods that cannot be 
overridden 


_| Abstract classes and methods 


NEWe- Modifies are prefixes that can be applied in various combinations to the methods and 
TERM variables within a class and, some, to the class itself. 


There is a long and varied list of modifiers. The order of modifiers is irredevant to their 
meaning— your order can vary and isreally amatter of taste. Pick astyleand then be consistent 
with it throughout all your classes. H ere is the recommended order: 


<access> static abstract synchronized <unusual> final native 


where <access> Can bé public, protected, OF private, and <unusual> includes volatile and 
transient. 


Note: As of the beta release, threadsate has been replaced by volatile. Both have 
to do with multithreading; no more will be said about them here (see D ay 18). 
transient iS a Special modifier used to declare a variable to be outside the persistent 
part of an object. T his makes persistent object storage systems easier to implement 
in Java, and though the compiler supports it, it is not used by the current J ava 
system. Several reserved keywords (byvalue, future, and generic, for example) may 
end up being <unusual> modifiers in later releases of J ava. In the beta system, none 
of these unusual modifiers appears in the source code for the standard J ava library 
Classes. 


All the modifiers are essentially optional; none have to appear in a declaration. Good style 
suggests adding as many as are needed to best describe the intended use of, and restrictionson, 
what you're declaring. In some special situations (inside an interface, for example, as described 
tomorrow), certain modifiers areimplicitly defined for you, and you needn't type then— they 
will be assumed to be there. 
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T hesynchronized modifier iscovered on D ay 18; it hasto do with multithreaded methods. T he 
native modifier is covered on D ay 20; it specifies that a method is implemented in the native 
language of your computer (usually C), rather than in J ava. H ow <access> modifiers apply to 
Classes is covered tomorrow. 


Method and Variable Access Control 


Access control is about controlling visibility. When a method or variable is visible to another 
Class, itsmethodscan reference (call or modify) that method or variable. T o “protect” amethod 
or variable from such references, you use the four levels of visibility described in the next 
sections. Each, in turn, is more restrictive, and thus provides more protection than the one 
before it. 


The Four P’s of Protection 


Learningyour four P’S( public, package, protected, and private) comesdown to understanding 
the fundamental relationships that a method or variable within a class can have to the other 
classes in the system. 


public 

Because any classisan island unto itself, thefirst of these relationships builds on thedistinction 
between theinside and the outside of the class. Any method or variable is visible to the class in 
which it is defined, but what if you want to make it visible to all the classes outside this class? 


T heanswer isobvious: simply declarethemethod or variableto havepub1ic access. Almost every 
method and variable defined in the rest of this book has been declared, for simplicity’s sake, 
public. When you use any of the examples provided in your own code, you'll probably decide 
to restrict this access further. B ecause you're just learning now, it’s not abad idea to begin with 
the widest possible access you can imagine and then narrow it down as you gain design 
experience, until theaccessthat each of your variablesand methodsshould havebecomessecond 
nature. H ere are some examples of public declarations: 

public class APublicClass { 


public int aPublicInt; 
public String aPublicString; 


public float aPublicMethod() { 


} 
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Note: T he two (or more) spaces after the prefix of modifiers and type in these 
declarations are intentional. T hey make finding the variable or method name 
within each linea little easier. Further in the book, you'll see that the type and the 
name are sometimes separately lined up in acolumn to make it even more evident 
what is what. When you get enough modifiers on aline, you'll begin to appreciate 
these small touches. 


A variable or method with public access has the widest possible visibility. Anyone can see it. 
Anyone can useit. Of course, this may not always be what you want— which brings us to the 
next level of protection. 


package 

InC, thereis the notion of hiding anameso that only the functions within a given sourcefile 
can see it. In Java, source files are replaced by the more explicit notion of packages, which can 
group classes (you learn about these tomorrow). For now, all you need to know is that the 
relationship you want to support is of aclassto its fellow implenentors of one piece of asystem, 
library, or program (or to any other grouping of related classes). T his defines the next level of 
increased protection and narrowed visibility. 


Due to an idiosyncrasy of the] ava language, this next level of access has no precise name. It is 
indicated by the lack of any access modifier in a declaration. H istorically, it has been called 
various suggestive names, including “friendly” and “package.” The latter usage seems most 
appropriateand is the one used here. Perhapsin a later release of the system, it will be possible 
to say package explicitly, but for now it is simply the default protection when none has been 
specified. 


Note: W hy would anyone want to make more typing for themselves and explicitly 
Say package? It isa matter of consistency and clarity. If you have a pattern of 
declarations with varying access modifier prefixes, you may always want the 
modifier to be stated explicitly, both for the reader’s benefit and because, in some 
contexts, different “default” levels of protection are being assumed, and you want 
the compiler to notice your intentions and warn you of any conflicts. 


M ost of the declarations you've seen in the past two weeks have used this default level of 
protection. H ere’s a reminder of what they look like: 


public class ALessPublicClass { 


int aPackageInt = 2; 
String aPackageString = "a1 anda"; 


float aPackageMethod() { // no access modifier means "package" 


} 
} 


public class AClassInTheSamePackage { 
public void testUse() { 
ALessPublicClass aLPC = new ALessPublicClass(); 


System.out.println(aLPC.aPackageString + aLPC.aPackagelInt) ; 
aLPC.aPackageMethod() ; // all of these are A.O.K. 


Note: If a class from any other package tried to access aLec the way that 
AClassInTheSamePackage does in this example, it would generate compile-time 
errors. (You'll learn how to create such classes tomorrow.) 


W hy was package Madea default? W hen you’re designing alargesystem and you partition your 
Classes into work groups to implement smaller pieces of that system, the classes often need to 
share alot morewith oneanother than with theoutside world. T heneed for this level of sharing 
iscommon enough that it was made the default level of protection. 


W hat if you have some details of your implementation that you don’t want to share with these 
“friends’? T he answer to this question leads us naturally to the next level of protection. 


protected 
Thethird relationship is between a class and its present and future subclasses. T hese subclasses 
are much closer to a parent class than to any other “outside” classes for the following reasons: 


Subclasses are usually more intimately aware of the internals of a parent class. 

[| Subclasses are often written by you or by someone to whom you’ve given your source 
code. 

Subclasses frequently need to modify or enhance the representation of the data within 
a parent class. 
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No onedseisallowed the privilege of thislevel of access; they must be content with the public 
face that the class presents. 


To support the level of intimacy reserved for subclasses, modern programming languages have 
invented an intermediate level of access between the previous two levels and full privacy. T his 
level gives more protection and narrows visibility still further, but still allows subclasses full 
access, In J ava, this level of protection is called, appropriately enough, protected: 

public class AProtectedClass { 


protected int aProtectedInt 
protected String aProtectedString 


4; 
"and a3 anda"; 


protected float aProtectedMethod() { 


} 
} 


public class AProtectedClassSubclass extends AProtectedClass { 
public void testUse() { 
AProtectedClass aPC = new AProtectedClass(); 


System.out.printin(aPC.aProtectedString + aPC.aProtectedInt) ; 
aPC.aProtectedMethod() ; // all of these are A.O.K. 


} 


public class AnyClassInTheSamePackage { 
public void testUse() { 
AProtectedClass aPC = new AProtectedClass(); 


System.out.printin(aPC.aProtectedString + aPC.aProtectedInt) ; 
aPC.aProtectedMethod() ; // NONE of these are legal 


} 


Even though AnyclassInTheSamePackage iSin the same package as aProtectedClass, it isnota 
subclass of it (it’s a subclass of object). O nly subclasses are allowed to see, and use, protected 
variables and methods. 


One of the most striking examples of the need for this special level of access is when you are 
supporting apublic abstraction with your class. Asfar astheoutsideworld isconcerned, you have 
asimple, public interface (via methods) to whatever abstraction you've built for your users. A 
more complex representation, and the implementation that depends on it, is hidden inside. 
W hen subclasses extend and modify this representation, or even just your implementation of 
it, they need to get to the underlying, concreterepresentation and not simply to the abstraction: 


public class SortedList { 
protected BinaryTree theBinaryTree; 


public Object[] theList() { 
return theBinaryTree.asArray(); 
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} 


public void add(Object o) { 
theBinaryTree.addObject(o) ; 
} 
} 


public class InsertSortedList extends SortedList { 

public void insert(Object 0, int position) { 

theBinaryTree.insertObject(o, position) ; 

} 
} 
Without being ableto access theBinaryTree directly, the insert () method hasto get thelist as 
an array of objects, viathepublic method theList (), allocateanew, bigger array, and insert the 
new object by hand. By “seeing” that its parent is using aBinaryTree to implement the sorted 
list, it can call Upon BinaryTree’s built-in method insertobject() to get thejob done 


Some languages, such as CLU, have experimented with more explicit ways of “raising” and 
“lowering” your level of abstraction to solve this same problem in a more general way. In J ava, 
protected Solves only apart of the problem, by allowing you to separate the concrete from the 
abstract; the rest is up to you. 


private 

Thefinal relationship comesfull circle, back to the distinction between the inside and outside 
of the class. private isthe most narrowly visible, highest level of protection that you can get— 
the diametric opposite of public. private methods and variables cannot be seen by any class 
other than the one in which they are defined: 

public class APrivateClass { 


private int aPrivateInt; 
private String aPrivateString; 


private float aPrivateMethod() { 


} 

} 

T hismay seem extremely restrictive, but it is, in fact, acommonly used level of protection. Any 
private data, internal state, or representations unique to your implenentation— anything that 
shouldn't bedirectly shared with subclasses— isprivate. Remember that an an object’s primary 
job isto encapsulate its data— to hideit from the world’s sight and limit its manipulation. The 
best way to do that isto make as much data as private as possible. Your methods can always be 
less restrictive, as you'll see below, but keeping a tight rein on your internal representation is 
important. It separates design from implenentation, minimizestheamount of information one 
class needs to know about another to get itsjob done, and reducestheextent of the codechanges 
you need when your representation changes. 
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The Conventions 
for Instance Variable Access 


A good ruleof thumb isthat unlessan instance variableisconstant (you'll soon seehow to specify 
this), itshould almost certainly beprivate. If you don’t do this, you havethefollowing problem: 
public class AFoolishClass { 

public String aUsefulString; 

: // set up the useful value of the string 
} 
T his class may have thought of setting up ausefulstring for the use of other classes, expecting 
them to (only) read it. Because it isn’t private, however, they can say: 


AFoolishClass aFC = new AFoolishClass(); 
aFC.aUsefulString = "oops!"; 


Because thereisno way to specify separately thelevel of protection for reading from and writing 
to instance variables, they should almost always be private. 


Note: T he careful reader may notice that this rule is violated in many examples in 
this book. M ost of these were just for clarity’s sake and to make the examples 
shorter and pithier. (You'll see soon that it takes more space to do the right thing.) 
O ne use cannot be avoided: the system. out .print() Calls scattered throughout the 
book must use the public Variable out directly. You cannot change this fina1 
system class (which you might have written differently). You can imagine the 
disastrous results if anyone accidentally modifies the contents of this (global) 
public Variable! 


Accessor Methods 
If instance variables are private, how do you give access to them to the outside world? T he 
answer is to write “accessor” methods: 


public class ACorrectClass { 
private String aUsefulString; 


public String aUsefulString() { // "get" the value 
return aUsefulString; 


} 
protected void aUsefulString(String s) { // "set" the value 
aUsefulString = s; 


} 
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U sing methodsto access an instance variableis oneof themost frequently used idiomsin object- 
oriented programs. Applyingit liberally throughout all your classes repays you numeroustimes 
over with more robust and reusable programs. N otice how separating the reading and writing 
of theinstancevariableallowsyou to specify apub1ic method to return itsvalueand aprotected 
method to set it. Thisis often a useful pattern of protections, because everyone probably needs 
to be able to ask for the value, but only you (and your subclasses) should be able to changeit. 
If itisa particularly private piece of data, you could makeits “set” method private and its “get” 
method protected, or any other combination that suits the data’s sensitivity to the light of the 
outside world. 


“) 


Warning: According to the beta language specification, it is not legal to have an 
instance variable and method by the same name. H owever, the beta compiler allows 
it! Because it is unclear what the final ruling on this conflict will be, use the simple 
naming scheme used previously for your programs. In alater release, if the compiler 
begins complaining, you can always change the method names to something less 
Clear. 


One of the alternate conventions for the naming of accessor methods is to prepend 
the variable name with the prefixes get and set. Besides making you type more— 
for alittle less clarity— this style forces you (by the capitalization conventions of 
Java) to write methods names such as setannoyingFirstCapitalLetter(). All thisis, 
of course, a matter of taste— just be consistent in using whatever convention you 
adopt. 


Whenever you want to append to your own instance variable, try writing this: 


aUsefulString(aUsefulString() + " some appended text"); 


Just like someone outside the class, you're using accessor methods to change aUsefulstring. 
W hy do this? 


You protected the variable in the first place so that changes to your representation would not 
affect the use of your class by others, but it still will affect the use of your class by you! Asin the 
abstract versus concrete discussion earlier, you should be protected from knowing too much 
about your own representation, except in those few places that actually need to know about it. 
Then, if you must change something about ausefulstring, it will not affect every use of that 
variable in your class (as it would without accessor methods); rather, it affects only the 
implementations of its accessor. 
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One of the powerful side effects of maintaining this level of indirection in accessing your own 
instancevariablesisthat if, at somelater date, somespecial codeneedsto beperformed each time 
aUsefulString IS accessed, you can put that codein oneplace, and all theother methodsin your 
class (and in everyone else's) will correctly call that special code. H ere’s an example: 
protected void aUsefulString(String s) { // the "set" method 

aUsefulString = s; 

performSomeImportantBookkeepingOn(s) ; 


} 

It may seem alittle difficult to get used to saying this: 
x(12 + 5 * «())3 

rather than this: 

x= 1245 * x; 


but the minor inconvenience will reward you with a rosy future of reusability and easy 
maintenance. 


Class Variables and Methods 


W hat if you want to create a shared variable that all your instances can see and use? If you use 
an instance variable, each instance has its own copy of thevariable, defeating its whole purpose. 
If you placeit in theclassitself, however, thereisonly onecopy, and all theinstances of theclass 
share it. T his is called a class variable: 


public class Circle { 
public static float pi = 3.14159265F; 


public float area(float r) { 


return pi*r * r; 


} 


ables and methods. W henever you see the word static, ranember to substitute 


JS Tip: Because of its historical ties, | ava uses the word static to declare class vari- 
mentally the word “class.” 


Instances can refer to their own class variables as though they were instance variables, asin the 
last example. Because it’s public, methods in other classes can also refer to pi: 


float circumference = 2 * Circle.pi * r; 
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Note: Instances of circie can also use this form of access. |n most cases, for clarity, 
this is the preferred form, even for instances. It clarifies that a class variable is being 
used, and helps the reader to know instantly where it’s used and that the variable is 
global to all instances. T his may seem pedantic, but if you try it yourself, you'll see 
that it can make things clearer. 


By the way, if you might change your mind later about how a class variable is 
accessed, created, and so forth, you should create instance (or even class) accessor 
methods to hide any uses of it from these changes. 


Class methodsaredefined analogously. T hey can be accessed in the sametwo ways by instances 
of their class, but only via the full class name by instances of other classes. H ere’s a class that 
defines class methods to help it count its own instances: 


public class InstanceCounter { 
private static int instanceCount = Q; // a class variable 


protected static int instanceCount() { // a class method 
return instanceCount; 


} 


private static void incrementCount() { 
++instanceCount; 


} 


InstanceCounter() { 
InstanceCounter.incrementCount() ; 

} 
} 
In this example, an explicit use of the class name calls the method incrementcount(). Though 
thismay seem verbose, in alarger program it immediately tellsthereader which object (theclass, 
rather than theinstance) is expected to handlethe method. T hisis especially useful if the reader 
needsto find wherethat method is declared in alarge class that places all itsclass methods at the 
top (the recommended practice, by the way). 


N ote the initialization of instancecount to o. Just as an instance variable is initialized when its 
instance is created, a class variable is initialized when its class is created. T his class initialization 
happens essentially before anything else can happen to that class, or itsinstances, so the classin 
the example will work as planned. 


Finally, theconventionsyou learned for accessing an instancevariableareapplied in thisexample 
to access a class variable. T he accessor methods are therefore class methods. (T hereis no “set” 
method here, just an increnent method, because no one is allowed to set instanceCount 
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directly.) N ote that only subclasses are allowed to ask what the instanceCount is, because that 
is a (relatively) intimate detail. H ere’s a test of InstanceCounter in action: 


public class InstanceCounterTester extends InstanceCounter { 
public static void main(String args[]) { 
for (int i = 0; i < 10; ++i) 
new InstanceCounter() ; 
System.out.printin("made " + InstanceCounter.instanceCount()); 
} 
} 


N ot shockingly, this example prints the following: 


made 10 


T he final Modifier 


Although it’s not the final modifier discussed, the tina1 modifier is very versatile: 

(| When the tina1 modifier is applied to a class, it means that the class cannot be 
subclassed. 
W hen it is applied to a variable, it means that the variable is constant. 


W hen it is applied to a method, it means that the method cannot be overridden by 
subclasses. 


final Classes 
H ere’s a final class declaration: 


public final class AFinalClass { 


} 


You declareaclass+ina1 for only two reasons. T hefirst issecurity. You expect to useitsinstances 
as unforgeable capabilities, and you don’t want anyoneeiseto beableto subclass and createnew 
and different instancesof them. T hesecond isefficiency. You want to count on instancesof only 
that one class (and no subclasses) being around in the system so that you can optimizefor them. 


Note: T he) ava class library uses finai classes extensively. You can flip through the 
class hierarchy diagrams in Appendix B to see them (finai classes are shaded darker 
than public Classes). Examples of the first reason to use final are the classes: 
java.lang.System and, from the package java.net, InetAddress and Socket. A 
good example of the second reason is java.lang.String. Strings are so common in 
Java, and so central to it, that the run-time handles them specially. 


It will be a rare event for you to create a fina class yourself, although you'll have plenty of 
opportunity to be upset at certain system classes being fina (thus making extending then 
annoyingly difficult). Oh well, such is the price of security and efficiency. Let’s hope that 
efficiency will beless of an issue soon, and some of these classes will become public onceagain. 


final Variables 
To declare constants in J ava, use final variables: 
public class AnotherFinalClass { 


public static final int aConstantInt 
public final String aConstantString 


123; 
"Hello world!"; 


Note: T he unusual spacing in the last line of the example makes it clearer that the 
top variable is a class variable and the bottom isn’t, but that both are public and 
final. 


final class and instance variables can be used in expressions just like normal class and instance 
variables, but they cannot bemodified. Asaresult, fina variablesmust begiven their (constant) 
value at the time of declaration. T hese variables function like a better, typed version of the 
#define Constants of C. Classes can provide useful constants to other classes via final class 
variables such as the one discussed previously. O ther classes reference them just as before: 
AnotherFinalClass.aConstantInt 


Local variables (those inside blocks of code surrounded by braces, for example, in while or for 
loops) can’t be declared fina1. (T hiswould bejust aconvenience, really, becausefinal instance 
variables work almost as well in this case) In fact, local variables can haveno modifiersin front 


of them at all: 
{ 

int aLocalVariable; // I'm so sad without my modifiers... 
} 


final Methods 


H ere’s an example of using final methods: 


public class MyPenultimateFinalClass { 
public static final void aUniqueAndReallyUsefulMethod() { 


} 
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public final void noOneGetsToDoThisButMe() { 


} 
} 


final methods cannot be overridden by subclasses. It isarare thing that amethod truly wants 
to declare itself the final word on its own implementation, so why does this modifier apply to 
methods? 


T heanswer isefficiency. If you declareamethod fina, the compiler can then “in-line” it right 
in the middle of methods that call it, becauseit “knows” that no one else can ever subclass and 
overridethe method to changeits meaning. Although you might not usefinai right away when 
writing aclass, asyou tunethesystem later, you may discover that afew methodshaveto ber inal 
to make your class fast enough. Almost all your methods will befine, however, just as they are. 


TheJavaclasslibrary declares alot of commonly used methods+tinai so that you'll benefit from 
the speed-up. In the case of classes that are already fina1, this makes perfect sense and isa wise 
choice. T he few fina1 methods declared in non-tina1 classes will annoy you— your subclasses 
can no longer overridethem. W hen efficiency becomesless of an issuefor the] avaenvironment, 
many of thesefinai methodscan be“unfrozen” again, restoring thislost flexibility to thesystem. 


Note: private methods are effectively fina1, as are all methods declared in a final 
Class. M arking these latter methods fina (as the J ava library sometimes does) is 
legal, but redundant; the current compiler already treats then as final. 


It’s possible to use final methods for some of the same security reasons you use 
final Classes, but it’s a much rarer event. 


If you use accessor methods a lot (as recommended) and are worried about efficiency, here’sa 
rewrite of AcorrectClass that’s much faster: 


public class ACorrectFinalClass { 
private String aUsefulString; 


public final String aUsefulString() { // now faster to use 
return aUsefulString; 


} 


protected final void aUsefulString(String s) { // also faster 
aUsefulString = s; 
} 


Note: Future Java compilers will almost certainly be smart enough to “in-line” 
simple methods automatically, so you probably won’t need to use final in such 
cases for much longer. 


abstract Methods and Classes 


Whenever you arrange classes into an inheritance hierarchy, the presumption is that “higher” 
classes are more abstract and general, whereas “lower” subclasses are more concrete and specific. 
Often, as you design a set of classes, you factor out common design and implenentation into 
ashared superclass. | f the primary reason that a superclass existsisto act asthiscommon, shared 
repository, and if only itssubclasses expect to be used, that superclassis called an abstract Class. 


abstract Classes can create no instances, but they can contain anything a normal class can 
contain and, in addition, areallowed to prefix any of their methodswith themodifier abstract. 
N on-abstract Classes arenot allowed to usethis modifier; usingit on even oneof your methods 
requires that your whole class be declared abstract. H ere’s an example: 


public abstract class MyFirstAbstractClass { 
int anInstanceVariable; 


public abstract int aMethodMyNonAbstractSubclassesMustImplement() ; 


public void doSomething() { 
// a normal method 
} 
} 


public class AConcreteSubClass extends MyFirstAbstractClass { 
public int aMethodMyNonAbstractSubclassesMustImplement() { 
// we *must* implement this method 
} 
} 


and some attempted uses of these classes: 


new MyFirstAbstractClass() ; // illegal, is abstract 


Object a 
c new AConcreteSubClass(); // OK, a concrete subclass 


Object 


N otice that abstract methods need no implementation; it is required that non-abstract 
subclasses provide an implementation. T he abstract Classsimply provides the template for the 
methods, which areimplemented by otherslater. In fact, in the] avaclasslibrary, thereareseveral 
abstract Classes that have no documented subclasses in the system, but simply provide a base 
from which you can subclass in your own programs. If you look at the diagrams in Appendix 
B, abstract Classes are shaded even darker than fina1 classes and are quite common in the 
library. 
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Using an abstract Class to embody a pure design— that is, nothing but abstract methods— is 
better accomplished in J avaby using an interface(discussed tomorrow). W henever adesign calls 
for an abstraction that includes instance state and/or a partial implementation, however, an 
abstract Classis your only choice. In previous object-oriented languages, abstract classes were 
simply a convention. T hey proved so valuable that J ava supports them not only in the form 
described here, but in the purer, richer form of interfaces, which will be described tomorrow. 


Summary 


T oday, you learned how variables and methods can control their visibility and access by other 
Classes via thefour P’sof protection: public, package, protected, and private. You also learned 
that, although instance variables are most often declared private, declaring accessor methods 
allows you to control the reading and writing of them separately. Protection levels allow you, 
for example, to separate cleanly your public abstractions from their concrete representations. 


You also learned how to create class variables and methods, which are associated with the class 
itself, and how to declare final variables, methods, and classes to represent constants, fast or 
secure methods, and classes, respectively. 


Finally, you discovered how to declare and use abstract Classes, which cannot be instantiated, 
and abstract methods, which haveno implementation and must be overridden in subclasses. 
T ogether, they provide a template for subclasses to fill in and act as a variant of the powerful 
interfaces of J ava that you'll study tomorrow. 


Q&A 


Q Why arethereso many different levels of protection in J ava? 


A Each leve of protection, or visibility, provides a different view of your class to the 
outside world. O ne view is tailored for everyone, one for classes in your own package, 
another for your class and its subclasses only, and the final one for just within your 
class. Each is a logically well-defined and useful separation that J ava supports directly 
in the language (as opposed to, for example, accessor methods, which are a convention 
you must follow). 


Won't using accessor methods everywhere slow down my Java code? 


N ot always. Soon, J ava compilers will be smart enough to make then fast automati- 
cally, but if you’re concerned about speed, you can always declare accessor methods to 
be final, and they'll be just as fast as direct instance variable accesses. 


p> oO 
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Are class (static) methods inherited just like instance methods? 


Yes, and no. The beta compiler still allows you to inherit them, but according to one 
of the oddest changes in the beta language specifications, static (class) methods are 
now fina1 by default. H ow, then, can you ever declare a non-fina1 class method? The 
answer is that you can’t! Inheritance of class methods is not allowed, breaking the 
symmetry with instance methods. Because this goes against a part of J ava’s philosophy 
(of making everything as simple as possible) perhaps it will be reversed in a later 
release. For now, follow the compiler and assume that class methods are inherited 
normally. 


Based on what I’ve learned, it seems like final abstract OF private abstract 
methods or classes don’t make sense. Are they legal? 

N ope, they’re compile-time errors, as you have guessed. T o be useful, abstract 
methods must be overridden, and abstract Classes must be subclassed, but neither of 
those two operations would be legal if they were also public OF final. 

What about static transient OF final transient? 

Those are also compile-time errors. Because a “transient” part of an object's state is 
assumed to be changing within each instance, it can not be static or final. This 
restriction matters only in the future, though, when transient is actually used by J ava. 
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When you examine a new language feature, you should ask yourself two questions: 


1. How can | use it to better organize the methods and classes of my J ava program? 
2. How can! useit while writing the} ava codein my methods? 


The first is often called programming in thelarge, and the second, programming in the small. 
Bill Joy, afounder of Sun M icrosystems, likes to say that J ava feels like C when programming 
in thesmall and like Smalltalk when programming in the large. W hat he means by that is that 
Java is familiar and powerful like any C-like language while you’re coding, but has the 
extensibility and expressive power of apure object-oriented languagelikeSmalltalk whileyou’re 
designing. 


The separation of “designing” from “coding” was one of the most fundamental advances in 
programming in the past few decades, and object-oriented languages such as] avaimplement a 
strong form of this separation. The first part of this separation has already been described on 
previous days: when you develop aj ava program, first you design the classes and decideon the 
relationships between these classes, and then you implement the J ava code needed for each of 
themethodsin your design. If you arecareful enough with both these processes, you can change 
your mind about aspects of the design without affecting anything but small, local pieces of your 
Java code, and you can change theimplementation of any method without affecting the rest of 
the design. 


Asyou begin to exploremoreadvanced J avaprogramming, however, you'll find that thissimple 
model becomes too limiting. T oday, you'll explore these limitations, for programming in the 
largeand in thesmall, to motivatetheneed for packages and interfaces. Let’sstart with packages. 


Packages 


Packages are J ava’s way of doing large-scale design and organization. T hey are used both to 
categorize and group classes. Let’s explore why you might need to use packages. 


Programming in the Large 


W hen you begin to develop J ava programs that use alarge number of classes, you will quickly 
discover some limitations in the model presented thus far for designing and building them. 


For onething, asthenumber of classes you build grows, thelikelihood of your wanting to reuse 
the short, simple name of some class increases. If you use classes that you've built in the past, 
or that someone elise has built for you (such as the classes in the J ava library), you may not 
remember— or even know— that these class names arein conflict. Being able to “hide” a class 
inside a package becomes useful. 
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H ere’s a simple example of the creation of a package in a] ava source file 


package myFirstPackage; 
public class MyPublicClass extends ItsSuperclass { 


} 


Note: | f a package Statement appears in aJ ava source file, it must be the first thing 
in that file (except for comments and white space, of course). 


You first declarethename of the package by using apackage statement. Then you define aclass, 
just as you would normally. T hat class, and any other classes also declared inside this same 
package name, are grouped together. (T hese other classes are usually located in other, separate 
source files.) 


Packages can be further organized into a hierarchy somewhat analogous to the inheritance 
hierarchy, whereeach “level” usually reoresentsa smaller, morespecific grouping of classes. The 
Java class library itself is organized along these lines (see the diagrams in Appendix B). The top 
level iscalled java; thenext level includes names such as io, net, util, and awt. Thelast has an 
even lower level, which includesthe package image. T hecolormode! Class, located in thepackage 
image, Can be uniquely referred to anywherein your J ava code aS java. awt.image.ColorModel. 


Note: By convention, the first level of the hierarchy specifies the (globally unique) 
name of the company that developed the J ava package(s). For example, Sun 

M icrosystem’s classes, which are not part of the standard Java environment, all 
begin with the prefix sun. T he standard package, java, isan exception to this rule 
because it is so fundamental and because it might someday be implemented by 
multiple companies. 


Starting with the beta release, Sun has specified a more formal procedure for 
package naming to be followed in the future. T he top-level package name space 
now reserves, for the use of this procedure, all the uppercase abbreviations used for 
top-level domains on the Internet (EDU, COM, GOV, FR, US, and so on). T hese 
reserved names form the first part of all new package names, which are prefixed by 
a reversed version of your domain name. By this procedure, the sun packages would 
be called com. sun. If you're further down in your company’s or university’s domain 
tree, you can keep reversing to your heart’s content: 

EDU. harvard.cs.projects.ai.learning.myPackage. Because domain names are 
already guaranteed to be unique globally, this nicely solves that thorny problem, 
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and as a bonus, the applets and packages from the potentially millions of J ava 
programmers out there will automatically be stored into a growing hierarchy below 
your classes directory, giving you a way to find and categorize them all ina 
comprehensible manne. 


Because each Java class should be located in a separate source file, the grouping of classes 
provided by a hierarchy of packages is analogous to the grouping of files into a hierarchy of 
directories on your file system. The] ava compiler reinforces this analogy by requiring you to 
createa directory hierarchy under your classes directory that exactly matches thehierarchy of the 
packages you have created, and to placeaclassinto the directory with thesamename (and level) 
as the package in which it’s defined. 


For example, the directory hierarchy for the Java class library exactly mirrors its package 
hierarchy. On UNIX, for example, theclass referenced aS java. awt . image.ColorModel isstored 
in afilenamed C olorM odal.classin the directory named .../classes/java/awt/image(the... isthe 
path where J ava was installed on your computer). In particular, if you have created a package 
within myFirstPackage called mySecondPackage, by declaring a Class: 


package myFirstPackage.mySecondPackage; 


public class AnotherPublicClass extends AnotherSuperclass { 


} 


the J ava source file (called AnotherPublicC lass.java) must be located in a directory below the 
current directory called classes/myF irstPackage/mySecondPackage for the compiler (javac) to 
find it. W hen thecompiler generates thefileAnotherP ublicC lass.class, it placesit into thissame 
directory so that the java interpreter can find it. Both the compiler and the interpreter expect 
(and enforce) the hierarchy. 


Note: T his also means that, for today’s first example, the source file would be 
named APublicC lass.java and located in the directory called classes/ 

myF irstPackage. W hat happens when, asin earlier examples in the book, classes are 
defined without a package statement? T he compiler places such classes in a default, 
unnamed package, and their .java and .class files can be located in the current 
directory or in the classes directory below it. 


To be more precise, any occurrence of the phrase “the current directory” in this 
section should be replaced by “any of the directories listed in the class path.” T he 
compiler and interpreter both search this list of paths to find any classes you 
reference. 


You can specify a class path on the command line when running javac or java, or 
more permanently, by changing a special environment variable called 
CLASSPATH. (For more details, read the documentation in your J ava release. ) 


Programming in the Small 


W hen you refer to aclass by namein your J avacode, you areusing apackage. M ost of the time 
you aren’t aware of it because many of the most commonly used classes in the systen arein a 
package that the J ava compiler automatically imports for you, called java.1ang. So whenever 
you saw this, for example: 


String aString; 


something more interesting than you might have thought was occurring. W hat if you want to 
refer to theclass you created at the start of this section, theonein the packagemyFirstPackage? 
If you try this: 


MyPublicClass someName; 


the compiler complains— the class myPublicClass isnot defined in the package java. lang. T 0 
solvethis problem, J avaallows any classnameto beprefixed by thenameof thepackagein which 
it was defined to form a unique reference to the class: 


myFirstPackage.MyPublicClass someName; 


Note: Recall that by convention, package names tend to begin with a lowercase 
letter to distinguish them from class names. T hus, for example, in the full name of 
the built-in string class, java.lang.String, it’s easier to separate the package name 
from the class name visually. 


Suppose you want to usea lot of classes from a package, a package with along name, or both. 
You don’t want to have to refer to your classes aS that.really.long.package.name.ClassName. 
Javaallowsyou to “import” the names of those classesinto your program. T hey then act just as 
java. lang Classes do, and you can refer to then without a prefix. For example, to use the really 
long class name in the last example more easily, you can write the following: 


import that.really.long.package.name.ClassName; 


ClassName anObject; 
// and you can use ClassName directly as many times as you like 
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Note: All import statements must appear after any package statement but before 
any class definitions. T hus, they are “stuck” at the top of your source file 


W hat if you want to useseveral classesfrom that same package? H ere’s an attempt from a(soon- 
to-be-tired) programmer: 

that.really.long.package.name.ClassOne first; 
that.really.long.package.name.ClassTwo second; 
that.really.long.package.name.ClassThree andSoOn; 

H ere’sonefrom amoresavvy programmer, who knowshow to import awholepackage of public 
Classes: 


import that.really.long.package.name.*; 


ClassOne first; 
ClassTwo second; 
ClassThree andSoOn; 


| Warning: T he asterisk (*) in this example is not exactly the one you might use at a 
s) command prompt to specify the contents of a directory. For example, if you ask to 
a list the contents of the directory classes/java/awt/*, that list includes all the .class 
files and subdirectories such as image and peer. Writing import java.awt.* doesnot 
import subpackages such aS image and peer. T 0 import all the classes in a complex 
package hierarchy, you must explicitly import each level of the hierarchy by hand. 


If you plan to useaclass or apackage only afew timesin your sourcefile, it’sprobably not worth 
importing it. The rule of thumb is to ask yourself: “D oes the loss in clarity I’d introduce by 
referring to just the class name outweigh the convenience of not having to type the extra 
characters?” If it does, don’t use import. Remember that the package name lets the reader know 
where to find more information about the class right at the place you're using it, rather than at 
the top of the file, where the import statements are located. 


W hat if you have the following in class A’s source file? 
package packageA; 

public class ClassName { 

; i 4 

public class ClassA { 


} 
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and in class B’s source file you have this: 

package packageB; 

public class ClassName { 

: tk 

public class ClassB { 

, er 

Then you the write the following, somewhere else: 


import packageA; 
import packageB; 


ClassName anObject; // which ClassName did you mean? 


There are two possible interpretations for the class you intended, onein packagea and onein 
packageB. Because thisis ambiguous, what should the poor compiler do? It generates an error, 
of course, and you haveto be more explicit about which one you intended. H ere’s an example: 


import packageA.*; 
import packageB.*; 


packageA.ClassName anObject; // now OK 
packageB.ClassName anotherObject; // also OK 


ClassA anAObject; // was never a problem 
ClassB aBObject; // ditto 


Note: You may wonder about the numerous declarations that appear as examples 
in today’s lesson. Declarations are good examples because they’re the simplest 
possible way of referencing aclass name. Any use of aclass name (in your extends 
clause, for example, or in new ClassName()) obeys the same rules. 


Hiding Classes 


T heastute reader may have noticed that the discussion of importing with an asterisk (*) stated 
that it imported a whole package of pub1ic classes. W hy would you want to have classes of any 
other kind? T ake alook at this: 


package collections; 


public class LinkedList { 
private Node root; 
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public void add(Object o) { 
root = new Node(o, root); 


} 
} 
class Node { // not public 
private Object contents; 
private Node next; 
Node(Object 0, Node n) { 
contents = 0; 
next =n; 
t 
} 


Note: If this were all in one file, you might be violating one of the compiler’s 
conventions: only one class should be located in each J ava source file. Actually, the 
compiler cares only about every public class being in a separate file (although it still 
is good style to use separate files for each class). 


The goal of the LinkedList class isto provide a set of useful public methods (such as add()) to 
any other classes that might want to use them. T hese other classes could care less about any 
support classes LinkedList needs to get its job done, and would prefer to not “see” them when 
using LinkedList. In addition, LinkedList may feel that the Node class is local to its implemen- 
tation and should not be seen by any other classes. 


For methods and variables, this would be addressed by the four Ps of protection discussed 
yesterday: private, protected, package, and public, listed in order of increasing visibility. 
You've already explored many public classes, and because both private and protected really 
make sense only when you're inside a class definition, you cannot put them outside of one as 
part of defining anew class. LinkedList might really like to say “only classes in my source file 
can see this class,” but because, by convention, each classislocated in a separate sourcefile, this 
would be a little needed, over-narrow approach. 


Instead, LinkedList declaresno protection modifier, which isequivalent to sayingpackage. N ow 
theclass can beseen and used only by other classesin the same packagein which it was defined. 
In this case, it’s the collections package. You might use LinkedList as follows: 


import collections.*; // only imports public classes 


LinkedList aLinkedList; 
/* Node n; */ // would generate a compile-time error 


aLinkedList.add(new Integer(1138) ); 
aLinkedList.add("THX-"); 


Note: You also can import or declarea LinkedList aS collections.LinkedList in 
this example. Because LinkedList refers to Node, that class is automatically loaded 
and used, and the compiler verifies that LinkedList (as part of package collec- 
tions) has the right to create and use the node class. You still do not have that right, 
though, just asin the example. 


O neof the great powers of hidden classes is that even if you use them to introduce a great deal 
of complexity into the implementation of some public Class, all the complexity ishidden when 
that class is imported. T hus, creating a good package consists of defining a small, clean set of 
public Classes and methods for other classes to use, and then implementing them by using any 
number of hidden (package) support classes. Y ou'll seeanother usefor hidden classeslater today. 


Interfaces 


Interfaces, likethe abstract classesand methodsyou saw yesterday, providetemplatesof behavior 
that other classes are expected to implement, but they are much more powerful. Let’s see why 
you might need such power. 


Programming in the Large 


When you first begin to design object-oriented programs, the class hierarchy seems almost 
miraculous. Within that single tree you can express a hierarchy of numeric types (number, 
complex, float, rational, integer), many simple-to-moderately-complex relationships between 
objectsand processesin theworld, and any number of pointsalongtheaxisfrom abstract/general 
to concrete/specific. After some deeper thought or more complex design experience, this 
wonderful tree begins to feel restrictive— at times, like a straitjacket. The very power and 
discipline you’veachieved by carefully placing only one copy of each ideasomewherein thetree 
can come back to haunt you whenever you need to cross-fertilize disparate parts of that tree. 


Some languages address these problems by introducing more flexible run-time power, such as 
the code block and the perform: method of Smalltalk; others choose to provide more complex 
inheritance hierarchies, such as multiple inheritance. W ith the latter complexity comes a host 
of confusing and error-proneambiguitiesand misunderstandings, and with theformer, aharder 
time implementing safety and security and a harder language to explain and teach. Java has 
chosen to take neither of these paths but, in the spirit of objective-C’'s protocols, has adopted 
a separate hierarchy altogether to gain the expressive power needed to loosen the straitjacket. 


T his new hierarchy is a hierarchy of interfaces. Interfaces are not limited to a single superclass, 
so they allow aform of multiple inheritance. But they passon only method descriptionsto their 
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children, not method implementations nor instance variables, which helps to eiminate many 
of the complexities of full multiple inheritance. 


Interfaces, like classes, are declared in source files, one interface to a file. Like classes, they also 
are compiled into .class files. In fact, almost everywhere that this book has aclass namein any 
of itsexamplesor discussions, you can substitute an interfacename. J ava programmers often say 
“class’ when they actually mean “class or interface.” Interfaces complement and extend the 
power of classes, and thetwo can be treated almost exactly thesame. O neof the few differences 
between them isthat an interfacecannot beinstantiated: newcan createonly an instanceof aclass. 
H ere’s the declaration of an interface: 


package myFirstPackage; 
public interface MyFirstInterface extends Interface1, Interface2, ... { 


i aad methods in here will be public and abstract 

// all variables will be public, static, and final 
} 
This example is a rewritten version of the first example in today’s lesson. It now adds a new 
public interface to the package myFirstPackage, instead of a new public class. Note that 
multiple parents can be listed in an interface’s extends clause. 


Note: If no extends clause is given, interfaces do not default to inheriting from 
Object, because object iS a Class. In fact, interfaces have no “topmost” interface 
from which they are all guaranteed to descend. 


Any variables or methods defined in a public interface are implicitly prefixed by the modifiers 
listed in the comments. Exactly those modifiers can (optionally) appear, but no others: 
public interface MySecondInterface { 


public static final int theAnswer = 42; // both lines OK 
public abstract int lifeTheUniverseAndEverything() ; 


long bingBangCounter = 0; // OK, becomes public, static, final 
long ageOfTheUniverse() ; // OK, becomes public and abstract 


protected int aConstant; // not OK 
private int getAnInt(); // not OK 


Note: If an interface is declared non-public (that is, package), NO public modifiers 
are implicitly prefixed. If you say public inside such an interface, you’re making a 
real statement of public-ness, not simply aredundant statement. It’s not often, 


though, that an interface is shared only by the classes inside a package, and not by 
the classes using that package as well. 


D esign Versus Implementation R evisited 

One of the most powerful things interfaces add to Java is the capability of separating design 
inheritance from implanentation inheritance. In the single-class inheritance tree, these two are 
inextricably bound. Sometimes, you want to be ableto describe an interfaceto aclass of objects 
abstractly, without having to implement a particular implementation of it yourself. You could 
create an abstract Class, such as those described yesterday. In order for anew class to use this 
type of “interface,” however, it has to become a subclass of the abstract class and accept its 
position in thetree. If this new class also needs to bea subclass of some other class in the tree, 
for implementation reasons, what could it do? W hat if it wants to use two such “interfaces” at 
once? W atch this: 


class FirstImplementor extends SomeClass implements MySecondInterface { 


: 


class SecondImplementor implements MyFirstInterface, MySecondInterface { 


} 


The first class above is “stuck” in the single inheritance tree just below the class someciass but 
is free to implement an interface as well. T he second class is stuck just below object but has 
implemented two interfaces (it could have implemented any number of then). Implementing 
an interface means promising to implement all the methods specified in it. 


Note: Although an abstract class is allowed to ignore this strict requirement, and 
can implement any subset of the methods (or even none of them), all its non- 
abstract Subclasses must still obey it. 


Becauseinterfaces arein a separate hierarchy, they can be “mixed-in” to the classesin the single 
inheritancetree, allowingthedesigne to sprinklean interfaceanywhereit isneeded throughout 
thetree. Thesingle-inheritance class tree can thus be viewed as containing only the implemen- 
tation hierarchy; the design hierarchy (full of abstract methods, mostly) is contained in the 
multipleinheritance interface tree. T hisis a powerful way of thinking about the organization 
of your program, and though it takes alittle getting used to, it’s also ahighly recommended one. 


Let's examine one simple example of this separation— creating the new class orange. Suppose 
you already have a good implementation of the class Fruit, and an interface, Fruitlike, that 
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represents what Fruits are expected to be able to do. You want an orange to bea fruit, but you 
also want it to be aspherical object that can be tossed, rotated, and so on. H ere’show to express 
it all: 

interface Fruitlike extends Foodlike { 


void decay(); 
void squish(); 


} 


class Fruit extends Food implements Fruitlike { 
private Color myColor; 
private int daysTilIRot; 


} 


interface Spherelike { 
void toss(); 
void rotate(); 


} 


class Orange extends Fruit implements Spherelike { 
// toss()ing may squish() me (unique to me) 
} 
You'll use this example again later today. For now, notice that class orange doesn’t have to say 
implements Fruitlike because, by extending Fruit, it already has! 


Note: T he reverse is not true, however. Implementing an interface implies nothing 
about the implementation hierarchy of a class. By the way, if you had used amore 
traditional way of designing classes (though not necessarily better), the class Fruit 
would be the interface description, as well as being the implementation. 


One of thenice things about this structure is that you can change your mind about what class 
Orange extends (if a really great sphere Class is suddenly implemented, for example), yet class 
Orange will still understand the same two interfaces: 


class Sphere implements Spherelike { // extends Object 
private float radius; 


} 


class Orange extends Sphere implements Fruitlike { 
// users of Orange never need know about the change! 
} 
The canonical use of the “mix-in” capability of interfaces is to allow several classes, scattered 
across the single-inheritance tree, to implement the same set of methods (or even just one). 
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Although these classes share acommon superclass (at worst, object), itislikely that below this 
common parent are many subclasses that are not interested in this set of methods. Adding the 
methods to the parent class, or even creating a new abstract Class to hold them and inserting 
it into the hierarchy above the parent, is not an ideal solution. 


Instead, use an interface to specify the method(s). It can be implenented by every class that 
shares the need and by none of the other classes that would have been forced to “understand” 
them in thesingleinheritancetree. (D esign isapplied only whereneeded.) U sersof theinterface 
can now specify variables and arguments to be of anew interface type that can refer to any of 
the classes that implement the interface (as you'll see below)— a powerful abstraction. Some 
examples of “mix-in” facilities are object persistence (via read() and write) methods), 
producing or consuming something (the Java library does this for images), and providing 
generally useful constants. T he last of these might look like this: 


public interface PresumablyUsefulConstants { 
public static final int oneOfThem = 1234; 
public static final float another = 1.234F; 
= "1234"; 


public static final String yetAnother 


} 


public class AnyClass implements PresumablyUsefulConstants { 
public static void main(String argV[]) { 
double calculation = oneOfThem * another; 


System.out.printin("hello " + yetAnother + calculation) ; 


} 

} 

T hisoutputsthe thoroughly meaninglesshe11lo 12341522.756, but in the process demonstrates 
that the class Anyclass can refer directly to all the variables defined in the interface 
PresumablyUsefulConstants. N ormally, you refer to such variables and constants via the class, 
as for the constant tInteger.mzn_vaLue, which is provided by the tnteger class. If a set of 
constants is large or is widely used, the shortcut of being able to refer to them directly (as 
oneOfThem rather than aSpresumablyUsefulConstants.oneOfThem) Makesit worth placing then 
into an interface and implementing it widely. 


Programming in the Small 


H ow do you actually use these interfaces? Remember that almost everywhere that you can use 
aclass, you can usean interfaceinstead. Let’stry to make useof theinterfacemysecondInterface 
defined previously: 


MySecondInterface anObject = getTheRightObjectSomehow() ; 


long age = anObject.ageOfTheUniverse(); 
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O nceyou declare anobj ect to beof typemysecondInterface, YOU Can USC anObj ect asthereceiver 
of any message that the interface defines (or inherits). W hat doesthe previous declaration really 
mean? 


W hen avariableisdeclared to beof an interfacetype, it simply meansthat any object thevariable 
refers to is expected to have implemented that interface— that is, it is expected to understand 
all the methods that interface specifies. It assumes that a promise made between the designer of 
the interface and its eventual implementors has been kept. Although this is a rather abstract 
notion, it allows, for example, thepreviouscodeto bewritten long beforeany classes that qualify 
are actually implemented (or even created!). In traditional object-oriented programming, you 
are forced to create a class with “stub” implementations to get the same effect. 


H ere’s amore complicated example: 


Orange anOrange 
Fruit aFruit 
Fruitlike aFruitlike 
Spherelike aSpherelike 


getAnOrange(); 

(Fruit) getAnOrange(); 
(Fruitlike) getAnOrange() ; 
(Spherelike) getAnOrange() ; 


aFruit.decay(); // fruits decay 
aFruitlike.squish(); // and squish 
aFruitlike.toss(); // not OK 
aSpherelike.toss(); // OK 

anOrange.decay(); // oranges can do it all 


anOrange.squish(); 
anOrange.toss(); 
anOrange.rotate(); 


Declarations and casts are used in this exampleto restrict an orangeto act morelikea merefruit 
or sphere, simply to demonstrate the flexibility of the structure built previously. If the second 
structure built (the one with the new sphere class) were being used instead, most of this code 
would still work. (In theline bearing Fruit, all instances of Fruit need to bereplaced by sphere. 
The later use of aFruit.decay() could be replaced by, for example, aSphere.rotate(). 
Everything else is the same.) 


Note: T he direct use of (implementation) class names is for demonstration pur- 
poses only. Normally, you would use only interface names in those declarations 
and casts so that none of the code in the example would have to change to support 
the new structure. 
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Interfaces are implemented and used throughout the] ava class library, whenever a behavior is 
expected to be implemented by anumber of disparate classes. |n Appendix B you'll find, for 
example, the interfaces java.lang.Runnable, java.util.Enumeration, java.util.Observable 

java.awt.image.ImageConsumer, and java.awt.image.ImageProducer. Let’s use one of these 
interfaces, Enumeration, to revisit theLinkedList example— and to tietogether today’slesson— 

by demonstrating a good use of packages and interfaces together: 


package collections; 


public class LinkedList { 
private Node root; 


public Enumeration enumerate() { 
return new LinkedListEnumerator (root) ; 
} 
} 


class Node { 
private Object contents; 
private Node next; 


public Object contents() { 
return contents; 


} 


public Node next() { 
return next; 
} 
} 


class LinkedListEnumerator implements Enumeration { 
private Node currentNode; 


LinkedListEnumerator(Node root) { 
currentNode = root; 


} 

public boolean hasMoreElements() { 
return currentNode != null; 

} 


public Object nextElement() { 
Object anObject = currentNode.contents(); 


currentNode = currentNode.next() ; 
return anObject; 
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H ereis atypical use of the enumerator: 


collections.LinkedList aLinkedList = createLinkedList(); 
java.util.Enumeration e = aLinkedList.enumerate(); 


while (e.hasMoreElements()) { 

Object anObject = e.nextElement(); 

// do something useful with anObject 
} 
N oticethat although you areusingtheenumeration e asthough you know what itis, you actually 
do not. In fact, it isan instance of a hidden class (LinkedListEnumerator) that you cannot see 
or usedirectly. By a combination of packages and interfaces, theLinkedList classhas managed 
to providea transparent public interfaceto some of its most important behavior (viathealready 
defined interface java.util. Enumeration) whilestill encapsulating (hiding) itstwo implemen- 
tation (support) classes. 


H anding out an object like this is sometime called vending. Often, the “vendor” gives out an 
object that a receiver can’t create itself, but that it knows how to use. By giving it back to the 
vendor, the receiver can prove it has a certain capability, authenticate itself, or do any number 
of useful tasks— all without knowing much about the vended object. This is a powerful 
metaphor that can be applied in a broad range of situations. 


Summary 


T oday, you learned how packages can be used to collect and categorize classes into meaningful 
groups. Packages are arranged in a hierarchy, which not only better organizes your programs, 
but allows you and the millions of Java programmers out on the N et to nameand share their 
projects uniquely with one another. 


You also learned how to use packages, both your own and themany preexisting onesin the] ava 
class library. 


You then discovered how to declareand useinterfaces, apowerful mechanism for extending the 
traditional single-inheritance of J ava’s classes and for separating the design inheritancefrom the 
implementation inheritancein your programs. Interfaces are often used to call shared methods 
when the exact class involved is not known. You'll see further uses of interfaces tomorrow and 
the day after. 


Finally, packages and interfaces can be combined to provide useful abstractions, such as 
Enumeration, that appear simple yet are actually hiding almost all their (complex) implenenta- 
tion from their users. T his is a powerful technique. 
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Q&A 


Q What will happen to package/directory hierarchies when some sort of archiving 
is added to Java? 


A Being able to download over the N et a whole archive of packages, classes, and re 
sources is something that J ava systems may soon be able to do. When this happens, 
the simple mapping between directory hierarchy and package hierarchy will break 
down, and you will not be able to tell as easily where each class is stored (that is, in 
which archive). Presumably these new, advanced J ava systems will provide tools that 
make this task (and compiling and linking your program in general) much easier. 


Q Can you say import some.package.B* to import all the classes in that package that 
begin with 5? 

A No, the import asterisk (*) does not act like a command-line asterisk. 

Then what exactly does import-ing with an * mean? 

A Combining everything said previously, this precise definition emerges: it imports all 
the public Classes that are directly inside the package named, and not inside one of its 
subpackages. (You can only import exactly this set of classes, or exactly one explicitly 
named class, from a given package.) By the way, J ava only “loads” the information for 
a class when you actually refer to that class in your code, so the « form of import iS no 
less efficient than naming each class individually. 


Q Is there any way that a hidden (package) class can somehow be forced out of 
hiding? 

A A bizarre case in which a hidden class can be forced into visibility occurs if it has a 
public Superclass and someone casts an instance of it to the superclass. Any public 
methods of that superclass can now be called via your hidden class instance, even if 
those methods were not thought of by you as public when overridden in the hidden 
class. U sually, these public methods are ones you don’t mind having your instances 
perform, or you wouldn't have declared them to have that public superclass. T his isn’t 
always the case. M any of the system’s built-in classes are public— you may have no 
choice. Luckily, this is a rare event. 


Why is full multiple inheritance so complex that Java abandoned it? 


A It’snot so much that it is too complex, but that it makes the language overly compli- 
cated— and as you'll learn on the final day, this can cause larger systems to be less 
trustworthy and thus less secure. For example, if you were to inherit from two 
different parents, each having an instance variable with the same name, you would be 
forced to allow the conflict and explain how the exact same references to that variable 
name in each of your superclasses, and in you (all three), are now different. Instead of 
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being able to call “super” methods to get more abstract behavior accomplished, you 
would always need to worry about which of the (possibly many) identical methods 
you actually wished to call in which parent. J ava’s run-time method dispatching would 
have to be more complex as well. Finally, because so many people would be providing 
classes for reuse on the N et, the normally manageable conflicts that would arise in 
your own program would be confounded by millions of users mixing and matching 
these fully multi-inherited classes at will. In the future, if all these issues are resolved, 
more powerful inheritance may be added to Java, but its current capabilities are 
already sufficient for 99 percent of your programs. 


abstract Classes don’t have to implement all the methods in an interface them- 
selves, but do all their subclasses have to? 


Actually, no. Because of inheritance, the precise rule is that an implementation must 
be provided by some class for each method, but it doesn’t have to be your class. T his is 
analogous to when you are the subclass of a class that implements an interface for you. 
W hatever the abstract Class doesn’t implement, the first nonabstract class below it 
must implenent. Then, any further subclasses need do nothing further. 


You didn’t mention callbacks. Aren’t they an important use of interfaces? 


Yes, but | didn’t mention them because a good example would be too bulky in the 
text. T hese callbacks are often used in user interfaces (such as window systems) to 
specify what set of methods are going to be sent whenever the user does a certain set of 
things (such as clicking the mouse somewhere, typing, and so forth). Because the user 
interface classes should not “know” anything about the classes using them, an 
interface's ability to specify a set of methods separate from the class tree is crucial in 
this case. Callbacks using interfaces are not as general as using, for example, the 
perform: method of Smalltalk, however, because a given object can request that a user 
interface object “call it back” only by using a single method name. Suppose that object 
wanted two user interfaces objects of the same class to call it back, using different 
names to tell them apart? It cannot do thisin J ava, and it is forced to use special state 
and tests to tell them apart. (I warned you that it was complicated!). So, although 
interfaces are quite valuable in this case, they are not the ideal callback facility. 
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Today, you'll learn about exceptional conditions in J ava: 


“| How to declare when you are expecting one 

“| How to handlethem in your code 

_| How to create them 

“| How your codeis limited, yet made more robust by then 


Let’s begin by motivating why new ways of handling exceptions were invented. 
Programming languages have long labored to solve the following common problem: 


int status = callSomethingThatAlmostAlwaysWorks() ; 


if (status == FUNNY RETURN VALUE) { 
// something unusual happened, handle it 
switch (someGlobalérror indicator) { 
: // handle more specific problems 


} ae { 
ee se. 28 // all is well, go your merry way 

} 

Somehow thisseems like alot of work to do to handlearare case. W hat’s worse, if the function 

called returns an int as part of its normal answer, you must distinguish one special integer 

(FUNNY_RETURN_VALUE) to indicate an error. W hat if that function really needs all the integers? 

You must do something even more ugly. 


Even if you manageto find adistinguished value (such asnutt in C for pointers, -1 for integers, 
and so forth), what if there are multiple errors that must be produced by the same function? 
Often, some global variable is used as an error indicator. The function stores a value in it and 
prays that no one else changes it before the caller gets to handle the error. M ultiple errors 
propagate badly, if at all, and there are numerous problems with generalizing this to large 
programs, complex errors, and so forth. 


Luckily, there is an alternative: using exceptions to help you handle exceptional conditions in 
your program, making the normal, nonexceptional code cleaner and easier to read. 


NEWe An exception is any object that is an instance of the class Throwable (or any of 
TERM its subclasses). 


Programming in the Large 


W hen you begin to build complex programsin J ava, you discover that after designing theclasses 
and interfaces, and their methodsdescriptions, you still havenot defined all thebehavior of your 
objects. After all, an interface describes thenormal way to usean object and doesn’t include any 
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strange, exceptional cases. |n many systems, the documentation takes care of this problem by 
explicitly listing the distinguished values used in “hacks” likethe previousexample. Becausethe 
system knows nothing about these hacks, it cannot check them for consistency. In fact, the 
compiler can do nothing at all to help you with these exceptional conditions, in contrast to the 
helpful warnings and errors it produces if a method is used incorrectly. 


M oreimportantly, you havenot captured in your design thisimportant aspect of your program. 
Instead, you areforced to makeup away to describeit in thedocumentation and hope you have 
not made any mistakes when you implement it later. W hat’s worse, everyone else makes up a 
different way of describingthesamething. Clearly, you need someuniform way of declaringthe 
intentionsof classes and methodswith respect to theseexceptional conditions. J avaprovidesjust 
such a way: 


public class MyFirstExceptionalClass { 
public void anExceptionalMethod() throws MyFirstException { 


} 
} 
H ere, you warn thereader (and thecompiler) that thecode. . . maythrow an exception called 
MyFirstException. 


You can think of amethod’s description asa contract between the designer of that method (or 
class) and you, the caller of the method. U sually, this description tells the types of a method’s 
arguments, what it returns, and the general semantics of what it normally does. You are now 
being told, as well, what abnormal things it can do. This is a promise, just like the method 
promises to return a value of a certain type, and you can count on it when writing your code. 
T hese new promises help to tease apart and make explicit all the places where exceptional 
conditions should be handled in your program, and that makes large-scale design easier. 


Because exceptions are instances of classes, they can be put into a hierarchy that can naturally 
describethe relationships among thedifferent types of exceptions. In fact, if you taeamoment 
to glancein Appendix B at the diagrams for java. 1ang-errors and java. 1ang-exceptions, you'll 
see that the class Throwabie actually has two large hierarchies of classes beneath it. T he roots of 
these two hierarchies are subclasses of Throwable Called Exception and Error. T hese hierarchies 
embody therich set of relationshipsthat exist between exceptionsand errorsin the] avarun-time 
environment. 


W hen you know that a particular kind of error or exception can occur in your method, you are 
supposed to either handleit yourself or explicitly warn potential callers about the possibility via 
the throws Clause. N ot all errors and exceptions must be listed; instances of either classerror or 
RuntimeException (or any of their subclasses) do not haveto belisted in your throws clause. T hey 
get special treatment because they can occur anywhere within aJ ava program and are usually 
conditions that you, as the programmer, did not directly cause. One good example is the 
OutOfMemoryError, which can happen anywhere, at any time, and for any number of reasons. 
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Note: You can, of course, choose to list these errors and run-time exceptions if you 
like, and the callers of your methods will be forced to handle them, just like anon- 
run-time exception. 


Whenever you see the word “exception” by itself, it almost always means “excep- 
tion or error” (that is, an instance of Throwable). T he previous discussion makes it 
Clear that Exceptions and Errors actually form two separate hierarchies, but except 
for the throws clause rule, they act exactly the same. 


If you examinethediagramsin Appendix B more carefully, you'll noticethat thereare only five 
types of exceptions (in java.1lang) that must be listed in a throws Clause (renember that all 
Errors and RuntimeExceptions are exempt): 

ClassNotFoundException 

IllegalAccessException 

InstantiationException 


InterrupedException 


NoSuchMethodException 


Each of these names suggests something that is explicitly caused by the programmer, not some 
behind-the-scenes event such as outofMemoryError. 


If you look further in Appendix B, near the bottom of thediagramsfor java.util and java. io, 
you'll see that each package adds some new exceptions. T he former is adding two exceptions 
somewhat akin to ArrayStoreException and IndexOutOfBoundsException, and so decides to 
place them under runtimeException. The latter is adding a whole new tree of 10Exceptions, 
which are more explicitly caused by the programmer, and so they are rooted under Exception. 
T hus, roExceptions must be described in throws Clauses. Finally, package java.awt defines one 
of each style, implicit and explicit. 


T he) avaclasslibrary uses exceptions everywhere, and to good effect. | f you examinethedetailed 
API documentation in your J ava release, you see that many of the methodsin the library have 
throws Clauses, and some of them even document (when they believe it will make something 
clearer to the reader) when they may throw oneof theimplicit errors or exceptions. T hisisjust 
anicety on the documente’s part, because you are not required to catch conditions like that. 
If it wasn’t obvious that such a condition could happen there, and for some reason you really 
cared about catching it, this would be useful information. 


Programming in the Small 


N ow that you havea feeling for how exceptionscan help you design aprogram and aclasslibrary 
better, how do you actually use exceptions? Let’s try to use anExceptionalMethod() defined in 
today’s first example: 


public void anotherExceptionalMethod() throws MyFirstException { 
MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass(); 


aMFEC.anExceptionalMethod() ; 

} 

Let's examine this example more closely. If you assume that myFirstException iS a Subclass of 
Exception, it meansthat if you don’t handleit in anotherExceptionalMethod()’SCode, you must 
warn your callersabout it. Becauseyour codesimply callSanExceptionalMethod() without doing 
anything about the fact that it may throw myFirstException, you must add that exception to 
your throws Clause. T hisisperfectly legal, but it does defer to your caller something that perhaps 
you should be responsible for doing yourself. (It depends on the circumstances, of course.) 


Supposethat that you feel responsibletoday and decideto handlethe exception. Because you’re 
now declaring amethod without a throws Clause, you must “catch” the expected exception and 
do something useful with it: 


public void responsibleMethod() { 
MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass() ; 


try { 
aMFEC.anExceptionalMethod() ; 


} catch (MyFirstException m) { 
A // do something terribly significant and responsible 


} 

} 

The try statement says basically: “T ry running the code inside these braces, and if there are 
exceptions thrown, | will attach handlers to take care of them.” (You first heard about these on 
D ay 10.) You can have as many catch Clauses at the end of atry as you need. Each allows you 
to handle any and all exceptions that are instances: of the class listed in parentheses, of any of 
its subclasses, or of aclassthat implementstheinterfacelisted in parentheses. In thecatch in this 
example, exceptions of the class myFirstException (or any of its subclasses) are being handled. 


W hat if you want to combine both the approaches shown so far? You'd like to handle the 
exception yourself, but also reflect it up to your caller. T hiscan bedone, by explicitly rethrowing 
the exception: 


public void responsibleExceptionalMethod() throws MyFirstException { 
MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass(); 


try { 
aMFEC.anExceptionalMethod() ; 
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} catch (MyFirstException m) { 
// do something responsible 
throw m; // re-throw the exception 

: } 

This works because exception handlers can be nested. You handle the exception by doing 
something responsible with it, but decide that it is too important to not give an exception 
handler that might bein your caller a chance to handle it as well. Exceptions float all the way 
up thechain of method callersthis way (usually not being handled by most of them) until at last, 
the system itself handles any uncaught ones by aborting your program and printing an error 
message. In a stand-alone program, thisis not such abad idea; but in an applet, it can causethe 
browser to crash. M ost browsers protect themselvesfrom thisdisaster by catching all exceptions 
themselves whenever they run an applet, but you can never tell. If it’s possible for you to catch 
an exception and do something intelligent with it, you should. 


Let’sseewhat throwing anew exception lookslike. H ow about fleshing out today’sfirst example: 


public class MyFirstExceptionalClass { 
public void anExceptionalMethod() throws MyFirstException { 


if (someThingUnusualHasHappened()) { 
throw new MyFirstException() ; 
// execution never reaches here 


} 


QY Note: throw is a little like a break statement— nothing “beyond it” is executed. 


This is the fundamental way that all exceptions are generated; someone, somewhere, had to 
create an exception object and throw it. In fact, the whole hierarchy under the class Throwable 
would beworth much less if there were not throw statements scattered throughout the codein 
the} ava library at just the right places. Because exceptions propagate up from any depth down 
inside methods, any method call you make might generate a plethora of possible errors and 
exceptions. Luckily, only the ones listed in the throws Clause of that method need be thought 
about; the rest travel silently past on their way to becoming an error message (or being caught 
and handled higher in the system). 


H ere’s an unusual demonstration of this, wherethe throw, and the handler that catcnesit, are 
very close together: 


System.out.print("Now "); 


try { 
System.out.print("is "); 
throw new MyFirstException() ; 
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System.out.print("a "); 
} catch (MyFirstException m) { 
System.out.print("the "); 
} 
System.out.print("time."); 
It prints out Now is the time. 
Exceptions are really a quite powerful way of partitioning the space of all possible error 
conditions into manageable pieces. Because the first catch Clause that matchesis executed, you 
can build chains such as the following: 
try { 
someReallyExceptionalMethod() ; 
} catch (NullPointerException n) { // a subclass of RuntimeException 
} catch (RuntimeException r) { // a subclass of Exception 17 
} catch (IOException i) { // a subclass of Exception 
} catch (MyFirstException m) { // our subclass of Exception 
} catch (Exception e) { // a subclass of Throwable 


} catch (Throwable t) { 
// Errors, plus anything not caught above are caught here 


} 

By listing subclasses before their parent classes, the parent catches anything it would normally 
catch that’s also not one of the subclasses aboveit. By juggling chains likethese, you can express 
almost any combination of tests. If there’s some really obscure case you can’t handle, perhaps 
you can usean interfaceto catch it instead. T hat allows you to design your (peculiar) exceptions 
hierarchy using multiple inheritance. Catching an interface rather than aclass can also be used 
to test for a property that many exceptions share but that cannot be expressed in the single 
inheritance tree alone. 


Suppose, for example, that a scattered set of your exception classes require a reboot after being 
thrown. Y ou createan interface called NeedsReboot, and all theseclassesimplement theinterface. 
(N one of them needs to have a common parent exception class.) Then, the highest level of 
exception handler simply catches classes that implement needsReboot and performs a reboot: 


public interface NeedsReboot { } // needs no contents at all 


try { 
someMethodThatGeneratesExceptionsThatImplementNeedsReboot () ; 
} catch (NeedsReboot n) { // catch an interface 
ee // cleanup 
SystemClass.reboot(); // reboot using a made-up system class 
} 


By the way, if you need really unusual behavior during an exception, you can placethe behavior 
into theexception classitself! Remember that an exception isalso anormal class, soit can contain 
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instance variablesand methods. Although using then isalittle peculiar, it might bevaluableon 
a few bizarre occasions. H ere’s what this might look like: 
try { 


someExceptionallyStrangeMethod() ; 
} catch (ComplexException e) { 


switch (e.internalState()) { // probably an instance variable value 
case e.COMPLEX_CASE: // a class variable of the exception 
e.performComplexBehavior(myState, theContext, etc); 
break; 
t 


T he Limitations Placed 
on the Programmer 


As powerful as all this sounds, isn’t it a little limiting, too? For example, suppose you want to 
override one of the standard methods of the object class, tostring(), to besmarter about how 
you print yourself: 
public class MyIllegalClass { 

public String toString() { 

easier mia’ ureter a 
// returns some String 

} 
} 
Becausethesuperclass (object) defined themethod declaration for tostring() without athrows 
clause, any implementation of it in any subclass must obey this restriction. In particular, you 
cannot just call someReallyExceptionalMethod(), aS you did previously, becauseit will generate 
ahost of errors and exceptions, someof which arenot exempt from beinglisted in athrows clause 
(such aS 10Exception and MyFirstException). If all the exceptions thrown were exempt, you 
would haveno problem, but becausesomearenot, you haveto catch at least thosefew exceptions 
for this to be legal J ava: 
public class MyLegalClass { 


public String toString() { 
try { 
someReallyExceptionalMethod() ; 
} catch (IOException e) { 
} catch (MyFirstException m) { 
} 


// returns some String 


} 


In both cases, you elect to catch the exceptions and do absolutely nothing with then. Although 
thisis legal, it isnot always theright thing to do. You may need to think for awhileto comeup 
with the best, nontrivial behavior for any particular catch clause. T his extra thought and care 
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makes your program morerobust, better ableto handle unusual input, and morelikely to work 
correctly when used by multiple threads (you'll see this tomorrow). 


MyI1legalClass’S toString() method produces a compiler error to remind you to reflect on 
these issues. T his extra care will richly reward you as you reuse your classes in later projects and 
in larger and larger programs. O f course, the} avaclass library has been written with exactly this 
degree of care, and that’s oneof thereasonsit’s robust enough to beused in constructing all your 
Java projects. 


T he finally Clause 


Finally, for finally. Suppose thereis someaction that you absolutely must do, no matter what 

happens. Usually, this is to free some external resource after acquiring it, to close a file after 17 
Opening it, or so forth. To be sure that “no matter what” includes exceptions as well, you use 

a clause of the try statement designed for exactly this sort of thing, fina1ly: 


SomeFileClass f = new SomeFileClass(); 


if (f.open("/a/file/name/path")) { 
try { 
someReallyExceptionalMethod() ; 
} finally { 
f.close(); 
} 
} 


T his use of finally behaves very much like the following: 


SomeFileClass f = new SomeFileClass(); 


if (f.open("/a/file/name/path")) { 
try { 
someReallyExceptionalMethod() ; 
} catch (Throwable t) { 
f.close(); 
throw t; 


} 


except that finally can also beused to clean up not only after exceptions but after return, break, 
and continue statements as well. H ere’s a complex demonstration: 


public class MyFinalExceptionalClass extends ContextClass { 
public static void main(String argv[]) { 
int mysteriousState = getContext(); 


while (true) { 
System.out.print("Who "); 


try { 
System.out.print("is "); 
if (mysteriousState == 1) 
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return; 
System.out.print("that "); 
if (mysteriousState == 2) 
break; 


System.out.print("strange "); 
if (mysteriousState == 3) 
continue; 
System.out.print("but kindly "); 
if (mysteriousState == 4) 
throw new UncaughtException() ; 
System.out.print("not at all "); 
} finally { 
System.out.print("amusing "); 
} 
System.out.print("yet compelling "); 
} 


System.out.print("man?"); 


} 
H ereis the output produced depending on the value of mysteriousState: 


1 Who is amusing 

2 Who is that amusing man? 

3 Who is that strange amusing Who is that strange amusing. . . 

4 Who is that strange but kindly amusing 

5 Who is that strange but kindly not at all amusing yet compelling man? 
Note: In case 3, the output never ends until you press Ctrl+C. In 4, an error 
message generated by the uncaughtException is also printed. 


Today, you learned about how exceptions aid your program’s design, robustness, and 
multithreading capability (more on this tomorrow). 


You also learned about the vast array of exceptions defined and thrown in the] ava class library, 
and how to try methodswhilecatch-ingany of ahierarchically ordered set of possibleexceptions 
and errors. Java's reliance on strict exception handling does place some restrictions on the 
programmer, but you learned that these restrictions are light compared to the rewards. 


Finally, the tinal1y clause was discussed, which provides a fool-proof way to be certain that 
something is accomplished, no matter what. 


Q&A 


Q 


A 


I’d like to test the last example you gave, but where does getcontext() come 
from? 


T hat example wasn't meant to be an executable program as it stands, but you can turn 
it into one as follows. First, renove the clause extends contextclass from line one. 
Then, replace getcontext() in the third line with 

Integer.parseInt(args[@]). YOU Can now compile, then run, the example via the 
following: 


java MyFinalExceptionClass N 
wheren is the mysterious state you want. 


I’m still not sure | understand the differences between Exceptions, Errors, and 17 
RuntimeExceptions. Is there another way of looking at them? 


Errors are caused by dynamic linking, or virtual machine problems, and are thus too 
low-level for most programs to care about (although sophisticated devedopment 
libraries and environments probably care a great deal about them). 

Runtime xceptions are generated by the normal execution of Java code, and though 
they occasionally reflect a condition you will want to handle explicitly, more often 
they reflect a coding mistake by the programmer and simply need to print an error to 
help flag that mistake. Exceptions that are not runtimeExceptions (10Exceptions, for 
example) are conditions that, because of their nature, should be explicitly handled by 
any robust and well-thought-out code. T he J ava class library has been written using 
only a few of these, but they are extremely important to using the system safely and 
correctly. The compiler helps you handle these exceptions properly via its throws 
clause checks and restrictions. 


Is there any way to “get around” the strict restrictions placed on methods by the 
throws Clause? 


Yes. Suppose you thought long and hard and have decided that you need to circum- 
vent this restriction. T his is almost never the case, because the right solution is to go 
back and redesign your methods to reflect the exceptions that you need to throw. 
Imagine, however, that for some reason a system class has you in a straitjacket. Your 
first solution is to subclass RuntimeException to makeup anew, exempt exception of 
your own. N ow you can throw it to your heart’s content, because the throws clause 
that was annoying you does not need to include this new exception. If you need a lot 
of such exceptions, an elegant approach is to mix in some novel exception interfaces to 
your new Runtime Classes. You're free to choose whatever subset of these new interfaces 
you want to catch (none of the normal runtime exceptions need be caught), while any 
leftover (new) Runtime exceptions are (legally) allowed to go through that otherwise 
annoying standard method in the library. 
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Q 


A 


I’m still a little confused by long chains of catch clauses. Can you label the 
previous example with which exceptions are handled by each line of code? 


Certainly, here it is: 


try { 
someReallyExceptionalMethod() ; 
} catch (NullPointerException n) { 
i ba // handles NullPointerExceptions 
} catch (RuntimeException r) { 
ota // handles RuntimeExceptions that are not NullPointerExceptions 
} catch (IOException i) { 
oe // handles IOExceptions 
} catch (MyFirstException m) { 
eis // handles MyFirstExceptions 
} catch (Exception e) { // handles Exceptions that are not RuntimeExceptions 
odes // nor IOExceptions nor MyFirstExceptions 
} catch (Throwable t) { 
// handles Throwables that are not Exceptions (i.e., Errors) 


} 

Given how annoying it can sometimes be to handle exceptional conditions 
properly, what’s stopping me from surrounding any method with a throws clause 
as follows: 


try { thatAnnoyingMethod(); } catch (Throwable t) { } 

and simply ignoring all exceptions? 

N othing, other than your own conscience. In some cases, you cnould do nothing, 
because it is the correct thing to do for your method's implementation. Otherwise, 


you should struggle through the annoyance and gain experience. Good styleisa 
struggle even for the best programmer, but the rewards are rich indeed. 
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T oday, you'll learn more about the threads mentioned briefly in W eek 2: 
“| How to “think multithreaded” 
“| How to protect your methods and variables from unintended thread conflicts 
“| How to create, start, and stop threads and threaded classes 
“| How the scheduler works in Java 


First, let's begin by motivating the need for threads. 


Threads are a relatively recent invention in the computer science world. Although processes, 
their larger parent, have been around for decades, threads have only recently been accepted into 
themainstream. W hat’sodd about thisisthat they arevery valuable, and programs written with 
them arenoticeably better, even to thecasual user. In fact, someof thebestindividual, H erculean 
efforts over the years have involved implementing a threads-like facility by hand to give a 
program amore friendly feel to its users. 


Imaginethat you're using your favoritetext editor on alargefile. W hen it starts up, doesit need 
to examine the entire file before it lets you edit? D oes it need to make a copy of the file? If the 
fileishuge, thiscan beanightmare. W ouldn’tit benicer for itto show you thefirst page, enabling 
you to begin editing, and somehow (in thebackground) completethe slower tasks necessary for 
initialization? Threads allow exactly this kind of within-the program parallelism. 


Perhaps the best example of threading (or lack of it) isa WWW browser. Can your browser 
download an indefinite number of files and W eb pages at once while still enabling you to 
continue browsing? W hile these pages are downloading, can your browser download all the 
pictures, sounds, and so forth in parallel, interleaving the fast and slow download times of 
multiple | nternet servers? H ot} ava can do all of these things— and more— by using the built- 
in threading of the J ava language. 


The Problem with Parallelism 


If threadingisso wonderful, why doesn’t every system haveit?M any modern operating systems 
havethe basic primitives needed to createand run threads, but they aremissingakey ingredient. 
Therest of their environment isnot thread-safe. | maginethat you arein athread, oneof many, 
and each of you is sharing some important data managed by the system. If you were managing 
that data, you could takestepsto protect it (asyou’ll seelater today), but thesystem is managing 
it. N ow visualize a piece of codein the system that reads some crucial value, thinks about it for 
awhile, and then adds 1 to the value: 

if (crucialValue > @) { 

Sona, & // think about what to do 

crucialValue += 1; 


} 
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Remember that any number of threads may be calling upon this part of thesystem at once The 
disaster occurs when two threads have both executed the it test before ether has incremented 
the crucialvalue. In that case, the valueis clobbered by then both with thesamecrucialvalue 
+ 1, and one of the increments has been lost. T his may not seem so bad to you, but imagine 
instead that the crucial value affects the state of the screen as it is being displayed. Now, 
unfortunate ordering of thethreads can cause the screen to be updated incorrectly. In the same 
way, mouseor keyboard eventscan belost, databases can be inaccurately updated, and so forth. 


T hisdisaster isinescapableif any significant part of the system has not been written with threads 
in mind. Therein lies the barrier to a mainstream threaded environment— the large effort 
required to rewriteexistinglibrariesfor thread safety. Luckily, J avawaswritten from scratch with 
thisismind, and every J ava classin its library is thread-safe. T hus, you now haveto worry only 
about your own synchronization and thread-ordering problems, because you can assume that 
the J ava system will do the right thing. 


NEWee- Atomic operations are operations that appear to happen “all at once’— exactly 
TERM atthesametime—to other threads. 


Note: Some readers may wonder what the fundamental problem really is. Can’t 
you just make the... areain the example smaller and smaller to reduce or eliminate 
the problem? W ithout atomic operations, the answer is no. Even if the 

.. took zero time, you must first look at the value of some variable to make any 
decision and then change something to reflect that decision. T hese two steps can 
never be made to happen at the same time without an atomic operation. Unless 
you're given one by the system, it’s literally impossible to create your own. 


Even the one line crucialvalue += 1 involves three steps: get the current value, add 
one to it, and store it back. (Using ++crucialvalue doesn’t help either.) All three 
steps need to happen “all at once” (atomically) to be safe. Special Java primitives, at 
the lowest levels of the language, provide you with the basic atomic operations you 
need to build safe, threaded programs. 


T hinking Multithreaded 


Getting used to threads takes a little while and a new way of thinking. Rather than imagining 
that you always know exactly what’s happening when you look at amethod you’vewritten, you 
have to ask yourself some additional questions. W hat will happen if morethan one thread calls 
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into this method at the same time? D o you need to protect it in some way? W hat about your 
class as a whole? Are you assuming that only one of its methods is running at the same time? 


Often you make such assumptions, and a local instance variable will be messed up as a result. 
Let's make a few mistakes and then try to correct them. First, the simplest case: 


public class ThreadCounter { 
int crucialValue; 


public void countMe() { 
crucialValue += 1; 


} 


public int howMany() { 
return crucialValue; 

} 
} 
T hiscode suffers from themost pureform of the “synchronization problen:” the+= takes more 
than onestep, and you may miscount thenumber of threadsasaresult. (D on’t worry about how 
threads are created yet, just imagine that a whole bunch of them are able to call countme(), at 
once, at slightly different times.) Java allows you to fix this: 


public class SafeThreadCounter { 
int crucialValue; 


public synchronized void countMe() { 
crucialValue += 1; 


} 


public int howMany() { 
return crucialValue; 

} 
} 
T hesynchronized keyword tells] avato maketheblock of codein the method thread safe. O nly 
onethread will beallowed insidethis method at once, and othershaveto wait until thecurrently 
running thread is finished with it before they can begin running it. This implies that 
synchronizing alarge, long-running method isalmost alwaysa bad idea. All your threadswould 
end up stuck at this bottleneck, waiting in single file to get their turn at this one slow method. 


It’s even worsethan you might think for most Unsynchronized variables. Because the compiler 
can keep them around in registers during computations, and a thread's registers can’t be seen 
by other threads (especially if they’re on another processor in atrue multiprocessor computer), 
a variable can be updated in such a way that no possible order of thread updates could have 
produced the result. T his is completely incomprehensible to the programmer. To avoid this 
bizarre case, you can label a variable volatile, meaning that you know it will be updated 
asynchronously by multiprocessor-like threads. Java then loads and stores it each time it’s 
needed and does not use registers. 


Note: In earlier releases, variables that were safe from these bizarre effects were 
labeled threadsafe. Because most variables are safe to use, however, they are now 
assumed to be thread-safe unless you mark them volatile. U Sing volatile Is an 
extremely rare event. In fact, in the beta release, the] ava library does not use 
volatile anywhere. 


Points About P oints 


The method howmany() in the last example doesn’t need to be synchronized, because it simply 
returns the current value of an instance variable. Someone higher in thecall chain may need to 
be synchronized, though— someone who uses the value returned from the method. H ere’s an 
example: 


public class Point { 
private float x, y; 


public float x() { // needs no synchronization 
return x; 

} 

public float y() { // ditto 
return y; 


// methods to set and change x and y 


} 


public class UnsafePointPrinter { 
public void print(Point p) { 
System.out.println("The point's x is " 
+ "and y is " 
} 
} 
Theanalogous methods to howmany() arex() and y(). They need no synchronization, because 
they just return the values of instance variables. It is the responsibility of the caller of x) and 
y() to decide whether it needs to synchronize itself— and in this case, it does. Although the 
method print ) simply reads values and prints them out, it reads two values. T his means that 
thereisachancethat some other thread, running between thecall to p.x ) and thecall top.y(), 
could have changed the value of x and y stored insidethePoint p. Remember, you don’t know 
how many other threads have a way to reach and call methods in thisPoint object! “Thinking 
multithreaded” comesdown to being careful any time you makean assumption that something 
has not happened between two parts of your program (even two parts of the same line, or the 
same expression, such as the string + expression in this example). 
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TryAgainP ointP rinter 


You could try to make a safe version of print() by simply adding the synchronized keyword 
modifier to it, but instead, let’s try a slightly different approach: 
public class TryAgainPointPrinter { 


public void print(Point p) { 
float safeX, safeyY; 


synchronized(this) { 
safeX = p.x(); // these two lines now 
safeY = p.y(); // happen atomically 
} 
System.out.print("The point's x is " + safex 
+" y is " + safeY); 
} 
} 
Thé@ synchronized statement takes an argument that says what object you would liketo lock to 
prevent morethan onethread from executing theenclosed block of codeat thesametime. H ere, 
you usethis (theinstanceitself), which is exactly the object that would have been locked by the 
synchronized method as a whole if you had changed print() to be like your safe countme( ) 
method. You have an added bonus with this new form of synchronization: you can specify 
exactly what part of amethod needs to be safe, and the rest can be left unsafe. 


N otice how you took advantage of this freedom to make the protected part of the method as 
small as possible, while leaving the string creations, concatenations, and printing (which 
together take a small but nonzero amount of time) outside the “protected” area. This is both 
good style (as a guide to the reader of your code) and more efficient, because fewer threads get 
stuck waiting to get into protected areas. 


SafeP ointP rinter 

T heastute reader, though, may still be worried by the last example. It seems asif you made sure 
that no one executes your callsto x) and y() out of order, but have you prevented the Point p 
from changing out from under you?T heanswer isno, you still havenot solved theproblem. You 
really do need the full power of the synchronized statement: 

public class SafePointPrinter { 


public void print(Point p) { 
float safeX, safeyY; 


synchronized(p) { // no one can change p 
safeX = p.x(); // while these two lines 
safeY = p.y(); // are happening atomically 


} 
System.out.print("The point's x is " + safex 
+" y is " + safeY); 


N ow you've got it. You actually needed to protect the Point p to protect from changes, so you 
lock it by giving it as the argument to your synchronized statement. Now when x() and y() 
happen together, they can be sure to get the current x and y of the Point p, without any other 
thread being ableto call amodifying method between. Y ou’re still assuming, however, that the 
Point p hasproperly protected itsdf. (You can alwaysassumethis about system classes— but you 
wrote this Point Class.) You can make sure by writing the only method that can change x and 
y inside p yourself: 


public class Point { 
private float x, y; 


// the x() and y() methods 


public synchronized void setXAndY(float newX, float newyY) { 
xX = newX; 
y = newyY; 
} 
} 
By making the only “set” method in Point synchronized, you guarantee that any other thread 
tryingto grab thepoint p and changeit out from under you hasto wait: you’velocked thePoint 
p with your synchronized(p) statement, and any other thread hasto try to lock the samePoint 
p Via the implicit synchronized(this) statement p now executes when entering setxandy(). 
Thus, at last, you are thread-safe. 


Note: By the way, if Java had some way of returning more than one value at once, 
you could write a synchronized getxAndy() method for points that returns both 
values safely. In the current J ava language, such a method could return anew, 
unique Point to guarantee to its callers that no one else has a copy that might be 
changed. T his sort of trick can be used to minimize the parts of the system that 
need to worry about synchronization. 


R eallySafeP oint 

Anadded benefit of theuseof the synchronized modifier on methods(or of synchronized(this) 
{. . .}) isthat only one of these methods (or blocks of code) can run at once. You can usethat 
knowledge to guarantee that only one of several crucial methods in a class will run at once: 


public class ReallySafePoint { 
private float x, y; 


public synchronized Point getUniquePoint() { 
return new Point(x, y); // can be a less safe Point 
} // because only the caller has it 
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public synchronized void setXAndY(float newX, float newyY) { 
x newX; 
y newY; 


} 


public synchronized void scale(float scalexX, float scaleY) { 
x *= scalex; 
y *= scaley; 

} 


public synchronized void add(ReallySafePoint aRSP) { 
Point p = aRSP.getUniquePoint(); 


X += p-x()5 
y t= p.y(); 
} // Point p is soon thrown away by GC; no one else ever saw it 

} 
T his example combines several of the ideas mentioned previously. To avoid a caller’shaving to 
synchronize(p) whenever getting your x and y, you give them a synchronized way to get a 
unique Point (like returning multiple values). Each method that modifies the object’s instance 
variables is also synchronized to prevent it from running between the x and y references in 
getUniquePoint() and from stepping on the others as they each modify the local x and y. N ote 
that add ) itself uses getuniquePoint() to avoid having to Say synchronized(aRSP). 


Classesthat arethissafearealittleunusual; it ismoreoften your responsibility to protect yourself 
from other threads’ use of commonly held objects (such as Points). Only when you know for 
certain that you're the only one that knows about an object, can you fully relax. Of course, if 
you created the object and gave it to no one else, you can be that certain. 


Protecting a Class Variable 
Finally, supposeyou want aclassvariableto collect someinformation acrossall aclass’sinstances: 


public class StaticCounter { 
private static int crucialValue; 


public synchronized void countMe() { 
crucialValue += 1; 


} 
} 
Isthis safe? If crucialvalue were an instance variable, it would be Because it’s a class variable, 
however, and there is only one copy of it for all instances, you can still have multiple threads 
modifying it by using different instances of the class. (Remember, the synchronized modifier 
locks the object this— an instance.) Luckily, you already know thetools you need to solvethis: 


public class StaticCounter { 
private static int crucialValue; 
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public void countMe() { 
synchronized(getClass()) { // can't directly reference StaticCounter 


crucialValue += 1; // the (shared) class is now locked 
} 
} 
} 
T hetrick isto “lock” on adifferent object— not on an instanceof theclass, but on theclassitself. 
Because a class variable is “inside” a class, just as an instance variable is inside an instance, this 
shouldn't be all that unexpected. In asimilar way, classes can provide global resources that any 
instance (or other class) can access directly by using theclass name, and lock by using that same 
classname. In thisexample, crucialvalue iSused from within an instanceof staticcounter, but 
if crucialvalue were declared public instead, from anywhere in the program, it would be safe 
to say the following: 
synchronized(new StaticCounter().getClass()) { 


StaticCounter.crucialValue += 1; 
} 


Note: T he direct use of another object’s variable is really bad style— it’s used here 
simply to demonstrate a point quickly. staticcounter normally provides a 
countMe()-like class method of its own to do this sort of dirty work. 


You can appreciate how much work the] ava team has done for you by thinking all these hard 
thoughts for each and every class (and method!) in the] ava class library. 


Cr 


eating and Using T hreads 


N ow that you understand thepower (and the dangers) of having many threadsrunningat once, 
how are those threads actually created? 


\ 


a 


of which is constantly doing the tedious task of garbage collection for you in the 
background. T here is also amain user thread that listens for events from your 
mouse and keyboard. If you’re not careful, you can sometimes lock out this main 
thread. If you do, no events are sent to your program and it appears to be dead. A 
good rule of thumb is that whenever you’re doing something that can bedoneina 
separate thread, it probably should be. T hreads in J ava are relatively cheap to create, 
run, and destroy, so don’t use them too sparingly. 


o Warning: T he system itself always has a few so-called daemon threads running, one 
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Becausethereisa class java. lang. Thread, you might guessthat you could createathread of your 
own by subclassing it— and you are right: 
public class MyFirstThread extends Thread { // a.k.a., java.lang.Thread 

public void run() { 

ciao // do something useful 

} 
} 
You now have a new type of Thread called myFirstThread, which does something useful 
(unspecified) when its run) method iscalled. O f course, no onehascreated thisthread or called 
its run() method, so it does absolutely nothing at the moment. To actually create and run an 
instance of your new thread class, you write the following: 


MyFirstThread aMFT = new MyFirstThread() ; 
aMFT.start(); // calls our run() method 


W hat could be simpler? You create a new instance of your thread class and then ask it to start 
running. Whenever you want to stop the thread, you use this: 


aMFT.stop() 5 


Besidesrespondingto start() and stop(), athread can also betemporarily suspended and later 
resumed: 


Thread t = new Thread(); 


t.suspend(); 

i ooh 8 // do something special while t isn't running 
t.resume(); 
A thread will automatically suspend() and then resume() when it’s first blocked at a synchro- 
nized point and then later unblocked (when it’s that thread’s “turn” to run). 


The Runnable Interface 


Thisisall well and good if every time you want to create athread you have the luxury of being 
ableto placeit under thethread classin thesingle-inheritanceclasstree. W hatif it morenaturally 
belongs under some other class, from which it needs to get most of its implementation? T he 
interfaces of D ay 16 come to the rescue: 
public class MySecondThread extends ImportantClass implements Runnable { 
public void run() { 
wee ta // do something useful 


} 
} 


By implementing theinterfacerunnable, you declare your intention to run in aseparate thread. 
In fact, the class Thread itself implements this interface, as you might expect from the design 
discussions on Day 16. As you also might guess from the example, the interface runnable 
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specifiesonly onemethod: run(). ASin myFirstThread, you expect someoneto createan instance 
of athread and somehow call your run() method. H ere’s how this is accomplished: 


MySecondThread aMST = new MySecondThread() ; 
Thread aThread = new Thread(aMST) ; 


aThread.start(); // calls our run() method, indirectly 


First, you create an instanceof mySecondThread. T hen, by passing thisinstanceto theconstructor 
making the new Threag, you makeit thetarget of that Thread. W henever that new Thread starts 
up, its run() method calls the run() method of the target it was given (assumed by the Thread 
to be an object that implements the Runnable interface). When start() is called, aThread 
(indirectly) callsyour run() method. You can stop aThread with stop().If you don’t need to talk 
to the Thread explicitly or to the instance of mysecondthreaa, here's a one line shortcut: 


new Thread(new MySecondThread()).start(); 


Note: As you can see, the class name, mySecondThread, iS a bit of a misnomer— it 
does not descend from Threaa, nor isit actually the thread that you start) and 
stop(). It probably should have been called mySecondThreadedClass OF 
ImportantRunnableClass. 


ThreadTester 


H ere’s a longer example: 


public class SimpleRunnable implements Runnable { 
public void run() { 
System.out.println("in thread named '" 
+ Thread.currentThread().getName() + "'"); 
} // any other methods run() calls are in current thread as well 


} 


public class ThreadTester { 
public static void main(String argv[]) { 
SimpleRunnable aSR = new SimpleRunnable(); 


while (true) { 
Thread t = new Thread(aSR) ; 


System.out.printin("new Thread() " + (t == null ? 
"fail" : "succeed") + "ed."); 
t.start(); 
try { t.join(); } catch (InterruptedException ignored) { } 
// waits for thread to finish its run() method 
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Note: You may be worried that only one instance of the class simp1eRunnable iS 
created, but many new Threads are using it. Don’t they get confused? Remember to 
separate in your mind the asr instance (and the methods it understands) from the 
various threads of execution that can pass through it. asr’s methods providea 
template for execution, and the multiple threads created are sharing that template. 
Each remembers where it is executing and whatever else it needs to make it distinct 
from the other running threads. T hey all share the same instance and the same 
methods. T hat’s why you need to be so careful, when adding synchronization, to 
imagine numerous threads running rampant over each of your methods. 


T heclassmethod currentThread() Can becalled to get thethread in which amethod iscurrently 
executing. If the simp1eRunnable Class were a subclass of Thread, its methods would know the 
answer already (it is the thread running). Because simplerunnable simply implements the 
interface Runnable, however, and counts on someone else (ThreadTester’Smain()) to createthe 
thread, itsrun() method needs another way to get itshandson that thread. O ften, you'll bedeep 
insidemethods called by your run() method when suddenly you need to get the current thread. 
The class method shown in the example works, no matter where you are. 


| Warning: You can do some reasonably disastrous things with your knowledge of 
threads. For example, if you're running in the main thread of the system and, 
a because you think you are in a different thread, you accidentally say the following: 


Thread.currentThread().stop() ; 
it has unfortunate consequences for your (soon-to-be-dead) program! 


The example then calls on getName), the current thread to get the thread’s name (usually 
something helpful, such as Thread -23) so it can tell theworld in which thread run() iSrunning. 
The final thing to note is the use of the method join), which, when sent to a thread, means 
“I’m planning to wait forever for you to finish your run() method.” You don’t want to do this 
lightly: if you haveanything elseimportant you need to get donein your thread any time soon, 
you can’t count on how long the join()ed thread may take to finish. In the example, its run() 
method is short and finishes quickly, so each loop can safely wait for the previous thread to die 
before creating the next one. (Of course, in this example, you didn’t have anything else you 
wanted to do while waiting for join() anyway.) H ere’s the output produced: 


new Thread() succeeded. 
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in thread named 'Thread-1' 
new Thread() succeeded. 

in thread named 'Thread-2' 
new Thread() succeeded. 

in thread named 'Thread-3' 
“Cc 


Ctrl+C was pressed to interrupt the program, because it otherwise would continue forever. 


NamedT hreadTester 


If you want your threads to have particular names, you can assign them yourself by using atwo- 
argument form of Threaa’s constructor: 


public class NamedThreadTester { 
public static void main(String argv[]) { 
SimpleRunnable aSR = new SimpleRunnable() ; 


for (int i 


= 1; true; ++i) { 
Thread t = 


new Thread(aSR, "" + (100 - i) 
+ " threads on the wall..."); 


System.out.printin("new Thread() " + (t == null ? 
"fail" : "succeed") + "ed."); 


t.start(); 
try { t.join(); } catch (InterruptedException ignored) { } 


} 


which takes a target object, as before, and astring, which names the new thread. H ere’s the 
output: 

new Thread() succeeded. 

in thread named '99 threads on the wall... 
new Thread() succeeded. 

in thread named '98 threads on the wall... 
new Thread() succeeded. 

in thread named '97 threads on the wall... 
ae 

N aminga thread is one easy way to pass it someinformation. T hisinformation flows from the 
parent thread to itsnew child. It’salso useful, for debugging purposes, to givethreadsmeaningful 
names (such aS network input) so that when they appear during an error— in astack trace, for 
example— you can easily identify which thread caused the problem. You might also think of 
using names to help group or organize your threads, but J ava actually provides you with a 
ThreadGroup Class to perform this function. A ThreadGroup allows you to group threads, to 
control them all asaunit, and to keep them from being able to affect other threads (useful for 


security). 


365 


Multithreading 


K nowing When a Thread has Stopped 


Let’s imagine a different version of the last example, one that creates a thread and then hands 
thethread off to other partsoftheprogram. Supposeit would then liketo know when that thread 
diesso that it can perform somecleanup operation. If simp1eRunnable werea Subclass of Thread, 
you might try to catch stop) whenever it’ssent— but look at Threaa’sdeclaration of thestop() 
method: 


public final void stop(); {.. . } 


The final here means that you can’t override this method in a subclass. In any case, 
SimpleRunnable iSnot a subclass of Thread, So how can thisimagined example possibly catch the 
death of its thread? T he answer is to use the following magic: 

public class SingleThreadTester { 


public static void main(String argv[]) { 
Thread t = new Thread(new SimpleRunnable() ); 


try { 
t.start(); 
someMethodThatMightStopTheThread(t) ; 

} catch (ThreadDeath aTD) { 
Sah // do some required cleanup 
throw aTD; // re-throw the error 


} 
} 
You understand most of this magic from yesterday's lesson. All you need to Know is that if the 
thread created in the exampledies, it throwsan error of classThreadDeath. T hecodecatchesthat 
error and performs the required cleanup. It then rethrows the error, allowing thethread to die. 
The cleanup code is not called if the thread exits normally (its run¢) method completes), but 
that’s fine; you posited that the cleanup was needed only when stop() was used on the thread. 


Note: T hreads can die in other ways— for example, by throwing exceptions that no 
one catches. In these cases, stop() iS never called, and the previous code is not 
sufficient. (If the cleanup always has to occur, even at the normal end of athread’s 
life, you can put it in a fina11y Clause.) Because unexpected exceptions can come 
out of nowhere to kill a thread, multithreaded programs that carefully catch and 
handle all their exceptions are more predictable, robust, and easier to debug. 
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You might wonder exactly what order your threads will berun in, and how you can control that 
order. Unfortunately, the current implementations of the] ava system cannot precisely answer 
the former, though with alot of work, you can always do the latter. 


NEWe- Thepart of the system that decides the real-time ordering of threads is called the 
TERM sthedule. 


Preemptive Versus Nonpreemptive 


Normally, any scheduler has two fundamentally different ways of looking at its job: non- 
preemptive scheduling and preemptive time-slicing. 


NEWe With non-preamptive scheduling, the scheduler runs the current thread forever, 
TERM. requiring that thread explicitly to tell it when it is safe to start a different thread. 
W ith preemptivetime-dicing, theschedule runsthe current thread until it has used up acertain 
tiny fraction of asecond, and then “preempts” it, suspend )Sit, and resume()S another thread 
for the next tiny fraction of a second. 


N on-preemptive scheduling is very courtly, always asking for permission to schedule, and is 
quite valuable in extremely time-critical, real-time applications where being interrupted at the 
wrong moment, or for too long, could mean crashing an airplane. 


M ost modern schedulers use preenptive timeslicing, because, except for a few time-critical 
cases, it has turned out to make writing multithreaded programs much easier. For one thing, it 
does not force each thread to decide exactly when it should “yield” control to another thread. 
Instead, every thread can just run blindly on, Knowingthat thescheduler will befair about giving 
all the other threads their chance to run. 


It turns out that thisapproach isstill not theideal way to schedule threads. You've given alittle 
too much control to thescheduler. T hefinal touch many modern schedulers add isto allow you 
to assign each thread apriority. T his creates atotal ordering of all threads, making somethreads 
more “important” than others. Being higher priority often means that a thread gets run more 
often (or gets more total running time), but it always means that it can interrupt other, lower- 
priority threads, even before their “timeslice” has expired. 


Thecurrent J ava release does not precisely specify the behavior of its scheduler. T hreadscan be 
assigned priorities, and when achoiceis made between several threads that all want to run, the 
highest-priority thread wins. H owever, amongthreadsthat areall thesamepriority, thebehavior 
isnot well-defined. In fact, the different platforms on which J ava currently runs have different 
behaviors— some behaving more like a preemptive scheduler, and some more like a non- 
preemptive scheduler. 
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Note: T his incomplete specification of the scheduler is terribly annoying and, 
presumably, will be corrected in later releases. N ot knowing the fine details of how 
scheduling occurs is perfectly all right, but not knowing whether equal priority 
threads must explicitly yidd or face running forever, is not all right. For example, 
all the threads you have created so far are equal priority threads, so you don’t know 
their basic scheduling behavior! 


Testing Your Scheduler 
To find out what kind of scheduler you have on your system, try the following: 
public class RunnablePotato implements Runnable { 
public void run() { 


while (true) 
System.out.printin(Thread.currentThread().getName() ); 


} 
public class PotatoThreadTester { 


public static void main(String argv[]) { 
RunnablePotato aRP = new RunnablePotato(); 


new Thread(aRP, "one potato").start(); 
new Thread(aRP, "two potato").start(); 


} 
For anon-preemptive scheduler, this prints the following: 
one potato 


one potato 
one potato 


forever, until you interrupt the program. For a preemptive scheduler that time-slices, it reoeats 


thelineone potato afew times, followed by thesamenumber of two potato lines, over and over: 


one potato 
one potato 


one potato 
two potato 
two potato 


two potato 
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until you interrupt the program. W hat if you want to be sure the two threads will take turns, 
no matter what the system scheduler wants to do? You rewrite RunnablePotato as follows: 
public class RunnablePotato implements Runnable { 
public void run() { 
while (true) { 


System.out.printin(Thread.currentThread().getName()) ; 
Thread.yield(); // let another thread run for a while 


Tip: N ormally you have to say Thread. currentThread().yield() to get your hands 
on the current thread, and then call yie1a(). Because this pattern isso common, 
however, the Thread Class provides a shortcut. 


The yie1a() method explicitly gives any other threads that want to run a chance to begin 
running. (If there are no threads waiting to run, the thread that made the yie1a() simply 
continues.) In our example, there's another thread that’sjust dyingto run, so when you now run 
the class threadTester, it should output the following: 


one potato 
two potato 
one potato 
two potato 
one potato 
two potato 


even if your system scheduler is non-preemptive, and would never normally run the second 
thread. 


P riorityT hreadTester 
To see whether priorities are working on your system, try this: 


public class PriorityThreadTester { 
public static void main(String argv[]) { 
RunnablePotato aRP new RunnablePotato(); 
Thread t1 new Thread(aRP, “one potato"); 
Thread t2 new Thread(aRP, “two potato"); 


t2.setPriority(t1.getPriority() + 1); 
ti.start(); 
t2.start(); // at priority Thread.NORM_ PRIORITY + 1 
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Tip: T he values representing the lowest, normal, and highest priorities that threads 
can be assigned are stored in class variables of the Thread Class: 

Thread.MIN PRIORITY, Thread.NORM PRIORITY, and Thread.MAX_PRIORITY. | he 
system assigns new threads, by default, the priority Thread. NORM_PRIORITY. Priori- 
ties in J ava are currently defined in a range from 1 to 10, with 5 being normal, but 
you shouldn't depend on these values; use the class variables, or tricks like the one 
shown in this example. 


If one potato isthe first line of output, your system does not preempt using priorities. 


W hy?| maginethat thefirst thread (t1) hasjust begun to run. Even beforeit hasachanceto print 
anything, along comes a higher-priority thread (t2) that wants to run right away. T hat higher- 
priority thread should preempt (interrupt) thefirst, and get achanceto print two potato before 
t1 finishes printing anything. In fact, if you use the RunnablePotato Class that never yield()S, 
t2 Staysin control forever, printing two potato lines, because it’s a higher priority than t1 and 
it never yields control. If you use the latest RunnablePotato Class (with yie1d()), the output is 
alternating lines of one potato and two potato as before, but starting with two potato. 


H ere’s a good, illustrative example of how complex threads behave: 


public class ComplexThread extends Thread { 
private int delay; 


ComplexThread(String name, float seconds) { 


super (name) ; 
delay = (int) seconds * 1000; // delays are in milliseconds 
start(); // start up ourself! 


public void run() { 
while (true) { 
System.out.printin(Thread.currentThread().getName() ); 
try { 
Thread.sleep(delay) ; 
} catch (InterruptedException ignored) { 


return; 
} 

} 

} 

public static void main(String argv[]) { 
new ComplexThread("one potato", 1.1F); 
new ComplexThread("two potato", Q.3F); 
new ComplexThread("three potato", 0.5F); 
new ComplexThread("four", Q.7F); 


T his example combines the thread and its tester into a singleclass. Its constructor takes care of 
naming (itself) and of starting (itself), becauseit isnow aThread. T hemain() method createsnew 
instances of its own class, because that class is a subclass of Thread. run() is also more 
complicated, because it now uses, for the first time, a method that can throw an unexpected 
exception. 


The Thread.sleep() method forcesthe current thread to yie1a() and then waits for at least the 
specified amount of time to elapse before allowing the thread to run again. It might be 
interrupted, however, while sleeping by another thread. In such a case, it throws an 
InterruptedException. N ow, becauserun() isnot defined asthrowing thisexception, you must 
“hide” the fact by catching and handling it yourself. Because interruptions are usually requests 
to stop, you should exit the thread, which you can do by simply returning from the run() 
method. 


T hisprogram should output arepeating but complex pattern of four different lines, whereevery 
once in a while you see the following: 


one potato 
two potato 
three potato 
four 


You should study the pattern output to proveto yourself that true parallelism is going on inside 
Java programs. You may also begin to appreciate that, if even thissimple set of four threads can 
produce such complex behavior, many more threads must be capable of producing near chaos 
if not carefully controlled. Luckily, J ava provides the synchronization and thread-safe libraries 
you need to control that chaos. 


Summary 


Today, you learned that parallelism is desirable and powerful, but introduces many new 
problems— methods and variables now need to be protected from thread conflicts— that can 
lead to chaos if not carefully controlled. 


By “thinking multithreaded,” you can detect the places in your programs that require 
synchronized statements (or modifiers) to make them thread-safe. A series of Point examples 
demonstrated the various levels of safety you can achieve and showed how subclasses of Threaa, 
or classesthat implement therunnable interface, arecreated and run() to generatemultithreaded 
programs. 


You also learned how to yie1a(), howto start(), stop(), suspend(), aNd resume) your threads, 
and how to catch ThreadDeath whenever it happens. 
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Finally, you learned about preemptive and non-preemptive scheduling, both with and without 
priorities, and how to test your Java system to see which of them your scheduler is using. 


T his wraps up the description of threads. You now know enough to write the most complex of 
programs: multithreaded ones. Asyou get morecomfortable with threads, you may begin to use 
the ThreadGroup Class or to usethe enumeration methods of Thread to get your hands on all the 
threads in the systen and manipulate them. Don’t be afraid to experiment; you can’t 
permanently break anything, and you learn only by trying. 


Q&A 


Q_ If they’re so important to Java, why haven’t threads appeared throughout the 
entire book? 


A Actually, they have Every stand-alone program written so far has “created” at least 
one thread, the one in which it is running. (O f course the system created that Thread 
for it automatically.) 


H ow exactly do these threads get created and run? W hat about applets? 


A When asimple, stand-alone] ava program starts up, the system creates a main thread, 
and its run() method calls your main() method to start your program— you do 
nothing to get that Thread. Likewise, when asimple applet loads into a] ava-aware 
browser, a Thread has already been created by the browser, and its run() method calls 
your init() and start() methods to start your program. In either case, a new Thread() 
of some kind was done somewhere, by the] ava environment itself. 


Q The ThreadTester Class had an infinite loop that created threads and then 
join()ed with them. Is it really infinite? 


A Intheory, yes. In actuality, how far the loop runs determines the resource limits of 
(and tests the stability of) the threads package and garbage collector in your Java 
release. O ver time, all J ava releases will converge on making the loop truly infinite. 


Q_ | know Java releases are still a little fuzzy about the scheduler’s behavior, but 
what's the current story? 


A Hereare the gruesome details for the beta release, relayed by Arthur van H off at Sun: 
the way J ava schedules threads “...depends on the platform. It is usually preemptive, 
but not always time-sliced. Priorities are not always observed, depending on the 
underlying implementation.” T his final clause gives you a hint that all this confusion 
isan implementation problem, and that someday soon, the design and implementa 
tion will both be clear about scheduling behavior. 


Ze) 
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D oes Java support more complex multithreaded concepts, such as semaphores? 


The class object in Java provides methods that can be used to build up condition 
variables, semaphores, and any higher-level parallel construct you might need. The 
method wait() (and its two variants with a timeout) causes the current thread to wait 
until some condition has been satisfied. The method notify() (OF notifyAll()), 
which must be called from within a synchronized method or block, tells the thread (or 
all threads) to wake up and check that condition again, because something has 
changed. By careful combinations of these two primitive methods, any data structure 
can be manipulated safely by a set of threads, and all the classical parallel primitives 
needed to implement published parallel algorithms can be built. 


My parallel friends tell me! should worry about something called “deadlock.” 
Should 1? 


N ot for simple multithreaded programs. H owever, in more complicated programs, 
one of the biggest worries does become one of avoiding a situation in which one 
thread has locked an object and is waiting for another thread to finish, while that 
other thread is waiting for the first thread to release that same object before it can 
finish. T hat’s a deadlock— both threads will be stuck forever. M utual dependencies 
like this involving more than two threads can be quite intricate, convoluted, and 
difficult to locate, much less rectify. T hey are one of the main challenges in writing 
complex multithreaded programs. 
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Today, you'll explore J ava’s streams: 


“| Input streams— and how to create, use, and detect the end of then— and filtered 
input streams, which can be nested to great effect 


“| Output streams, that are mostly analogous to (but the inverse of) input streams 


You'll also learn about two stream interfaces that makethe reading and writing of typed streams 
much easier (aswell as about several utility classes used to accessthefilesystem). Let’s begin with 
alittle history behind the invention of streams. 


One of the early inventions of the UNIX operating system was the pipe. By unifying all these 
disparateways of communicatinginto asinglemetaphor, U N1X paved theway for awholeseries 
of related inventions, culminating in the abstraction known as streams. 


NEWe- A pipeisan uninterpreted stream of bytes that can be used for communicating between 
TERM programs (or other “forked” copies of your own program) or for reading and writing to 
peripheral devices and files. 


A cream isapath of communication between thesourceof someinformation and itsdestination. 


That information, an uninterpreted byte stream, can come from any “pipe source,” the 
computer’s memory, or even from the Internet. In fact, the source and destination of a stream 
arecompletely arbitrary producers and consumers of bytes, respectively. T herein liesthe power 
of the abstraction. You don’t need to know about the source of the information when reading 
from astream, and you don’t need to know about the final destination when writing to one. 


General-purpose methods that can read from any source accept a stream argument to specify 
that source; general methods for writing accept a stream to specify the destination. Arbitrary 
processors(or filters) of datahavetwo stream arguments. T hey read from thefirst, processthedata, 
and write the results to the second. T hese processors have no idea of either the source or the 
destination of the data they are processing. Sources and destinations can vary widely: from two 
memory bufferson thesamelocal computer, to theELF transmissionsto and from a submarine 
at sea, to the real-time data streams of aN ASA probe in deep space. 


By decoupling the consuming, processing, or producing of data from the sources and 
destinations of that data, you can mix and match any combination of them at will as you write 
your program. In the future, when new, previously nonexistent forms of source or destination 
(or consumer, processor, or producer) appear, they can beused within thesameframework, with 
no changes to your classes. N ew stream abstractions, supporting higher levels of interpretation 
“on top of” the bytes, can be written completely independently of the underlying transport 
mechanisms for the bytes themselves. 
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At the pinnacle of this stream framework are the two abstract Classes, InputStream and 
OutputStream. If you turn briefly to thediagram for java.io in AppendixB, you'll seethat below 
these classes is a virtual cornucopia of categorized classes, demonstrating the wide range of 
streams in the system, but also demonstrating an extremely well-designed hierarchy of 
relationships between these streams, onewell worth learning from. Let’s begin with the parents 
and then work our way down this bushy tree. 


Input Streams 


All the methods you will explore today are declared to throw I0Exceptions. T his new subclass 
Of Exception conceptually embodies all the possible |/O errors that might occur while using 
streams. Several subclasses of it defineafew, morespecific exceptionsthat can bethrown aswell. 
For now, it isenough to know that you must either catch an I0Exception, or bein amethod 
that can “pass it along,” to be a well-behaved user of streams. 


T he abstract Class InputStream 


InputStream iS aN abstract Class that defines the fundamental ways in which a destination 
consumer readsa stream of bytes from some source. T heidentity of thesource, and the manner 
of thecreation and transport of thebytes, isirrelevant. W hen using an input stream, you arethe 
destination of those bytes, and that’s all you need to know. 


read() 


Themostimportant method to theconsume of an input stream istheonethat reads bytesfrom 
thesource. T hismethod, read(), comesin many flavors, and each isdemonstrated in an example 
in today’s lesson. 


Each of theseread() methodsis defined to “block” (wait) until all theinput requested becomes 
available. D on’t worry about this limitation; because of multithreading, you can do as many 
other thingsas you like whilethisonethread is waiting for input. In fact, it isacommon idiom 
to assign athread to each stream of input (and for each stream of output) thatissolely responsible 
for reading from it (or writing to it). T heseinput threads might then “hand off” theinformation 
to other threads for processing. T his naturally overlaps the 1/O time of your program with its 
compute time. 


H ere’s the first form of read(): 


InputStream s 
byte[] buffer 


= getAnInputStreamFromSomewhere() ; 
= new byte[1024]; // any size will do 
if (s.read(buffer) != buffer.length) 

System.out.printin("I got less than I expected."); 
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Note: H ere, and throughout the rest of today’s lesson, assume that either an import 
java.io appears before all the examples or that you mentally prefix all references to 
java.io Classes with the prefix java. io. 


This form of read) attenptsto fill the entire buffer given. If it cannot (usually dueto reaching 
theend of theinput stream), it returnstheactual number of bytesthat were read into the buffer. 
After that, any further callsto reaa() return -1, indicating that you are at theend of thestream. 
N ote that the it statement still works even in this case, because -1 != 1024 (this corresponds 
to an input stream with no bytesin it all). 


Note: D on’t forget that, unlikein C, the -1 casein J ava is not used to indicate an 
error. Any l/O errors throw instances of 1oException (which you're not catching 
yet). You learned on D ay 17 that all uses of distinguished values can be replaced by 
the use of exceptions, and so they should. The -1 in the last example is a bit of a 
historical anachronism. You'll soon see a better approach to indicating end of the 
stream using the class pataInputStream. 


You can also read into a “slice” of your buffer by specifying the offset into the buffer, and the 
length desired, as arguments to read(): 


s.read(buffer, 100, 300); 


T his exampletriesto fill in bytes 100 through 399 and behaves otherwise exactly the same asthe 
previouSread() method. In fact, in the current release, the default implementation of theformer 
version Of read() uses the latter: 


public int read(byte[] buffer) throws IOException { 
return read(buffer, 0, buffer.length) ; 


Finally, you can read in bytes oneat atime 


InputStream s = getAnInputStreamFromSomewhere() ; 


byte ; 
int byteOrMinus1 ; 
while ((byteOrMinus1 = s.read()) != -1) { 


b = (byte) byteOrMinus1; 
// process the byte b 


// reached end of stream 


Note: Because of the nature of integer promotion in J avain general, and because in 
this case the reaa() method returns an int, using the byte typein your code may 
bea little frustrating. You'll find yourself constantly having explicitly to cast the 
result of arithmetic expressions, or of int return values, back to your size. Because 
read() really should be returning a byte in this case, | feel justified in declaring and 
using it as such (despite the pain)— it makes the size of the data being read clearer. 
In cases wherein you feel the range of a variable is naturally limited to a byte (ora 
short) rather than an int, please take the time to declare it that way and pay the 
small price necessary to gain the added clarity. By the way, alot of the] ava class 
library code simply stores the result of read() in an int. T his proves that even the 
Java team is human— everyone makes style mistakes. 


skip() 
W hat if you want to skip over someof the bytesin astream, or start reading astream from other 
than its beginning? A method similar to reaa() does the trick: 
if (s.skip(1024) != 1024) 

System.out.printin("I skipped less than I expected."); 
Thisskips over the next 1024 bytesin the input stream. skip) takes and returnsalong integer, 
because streamsare not required to belimited to any particular size. T hedefault implementation 
of skip in this release simply uses read(): 


public long skip(long n) throws IOException { 
byte[] buffer = new byte[(int) n]; 


return read(buffer) ; 


Note: T his implementation does not support large skips correctly, because its 1ong 
argument is cast to an int. Subclasses must override this default implementation if 
they want to handle this more properly. T his won't be as easy as you might think, 
because the current release of the] ava system does not allow integer types larger 
than int to act as array subscripts. 
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available() 
|f for somereason you would liketo know how many bytes arein the stream right now, you can 
ask: 
if (s.available() < 1024) 

System.out.printlin("Too little is available right now."); 
T histellsyou thenumber of bytesthat you can reaa() without blocking. Becauseof the abstract 
natureof thesourceof thesebytes, streams may or may not beableto tell you areasonableanswer 
to this question. For example, some streams always return a. U nless you use specific subclasses 
Of InputStream that you know provide a reasonable answer to this question, it’s not a good idea 
to rdy upon this method. Renember, multithreading ediminates many of the problens 
associated with blocking while waiting for a stream to fill again. Thus, one of the strongest 
rationales for the use of available() goes away. 


mark() and reset() 


Some streams support the notion of marking a position in the stream, and then later resetting 
the stream to that position to reread the bytes there. Clearly, the stream would have to 
“remember” all those bytes, so thereisa limitation on how far apart in a stream the mark and 
its subsequent reset can occur. There’s also a method that asks whether or not the stream 
supports the notion of marking at all. H ere’s an example: 


InputStream s = getAnInputStreamFromSomewhere() ; 


if (s.markSupported()) { // does s support the notion? 
ay ae, os // read the stream for a while 
s.mark(1024) ; 
Be cis x // read less than 1024 more bytes 
s.reset(); 
ie at 38 // we can now re-read those bytes 
} else { 
ml ie ie // no, perform some alternative 

} 

When marking astream, you specify the maximum number of bytes you intend to allow to pass 
before resetting it. This allows the stream to limit the size of its byte “memory.” If thisnumber 
of bytes goes by and you have not yet reset), the mark becomes invalid, and attempting to 


reset() will throw an exception. 


M arking and resetting a stream is most valuable when you are attempting to identify the type 
of thestream (or thenext part of thestream), but to do so, you must consumeasignificant piece 
of it in the process. O ften, this is because you have several black-box parsers that you can hand 
the stream to, but they will consume some (unknown to you) number of bytes before making 
up their mind about whether the stream is of their type. Set alargesize for theread limit above, 
and let each parser run until it ether throws an error or completes a successful parse. I f an error 
isthrown, reset() and try the next parser. 


close() 

Because you don’t know what resources an open stream represents, nor how to deal with then 
properly when you're finished reading the stream, you must usually explicitly close down a 
stream so that it can release these resources. Of course, garbage collection and a finalization 
method can do thisfor you, but what if you need to reopen that stream or thoseresources before 
they have been freed by this asynchronous process? At best, this is annoying or confusing; at 
worst, it introduces an unexpected, obscure, and difficult-to-track-down bug. Because you're 
interactingwith theoutsideworld of external resources, it’ssafer to beexplicit about when you’re 
finished using them: 


InputStream s = alwaysMakesANewInputStream() ; 


try { 

ee oe // use s to your heart's content 

} finally { 
s.close(); 

} 

Get used to thisidiom (using finally); it’s a useful way to be sure something (such as closing 

the stream) always gets done. Of course, you’re assuming that the stream is always successfully 

created. If thisisnot always the case, and nu11 is sometimes returned instead, here’s the correct 

way to be safe: 


InputStream s = tryToMakeANewInputStream() ; 


if (s != null) { 
try { 
} finally { 
s.close(); 


} 


All input streams descend from the abstract Class InputStream. All sharein common the few 
methods described so far. T hus, stream s in the previous examples could have been any of the 
more complex input streams described in the next few sections. 


B yteArrayl nputStream 


The“inverse” of someof theprevious examples would beto createan input stream from an array 
of bytes. T his is exactly what ByteArrayInputStream does: 


byte[] buffer = new byte[1024]; 
fillWithUsefulData(buffer) ; 


InputStream s = new ByteArrayInputStream(buffer) ; 
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Readersof thenew stream s seea stream 1024 byteslong, containingthebytesin thearray butter. 
Just aS read() has a form that takes an offset and a length, so does this class's constructor: 


InputStream s = new ByteArrayInputStream(buffer, 100, 300); 


H ere, the stream is 300 bytes long and consists of bytes 100-399 from the array buffer. 


Note: Finally, you've seen your first examples of the creation of a stream. T hese 
new streams are attached to the simplest of all possible sources of data, an array of 
bytes in the memory of the local computer. 


ByteArrayInputStreams only implement the standard set of methods that all input streams do. 
H ere, however, theavailable() method hasa particularly simplejob— it returns 1024 and 300, 
respectively, for the two instances of ByteArrayInputStream yOu Created previously, because it 
knowsexactly how many bytesareavailable Finally, callingreset() ON aByteArrayInputStream 
resets it to the beginning of the stream (buffer), no matter where the mark is set. 


Filel nputStream 


O neof the most common uses of streams, and historically the earliest, isto attach them to files 
in thefilesystem. H ere, for example, isthe creation of such an input stream on aU NIX system: 


InputStream s = new FileInputStream("/some/path/and/fileName") ; 


| Caution: Applets attenpting to open, read, or write streams based on files in the 
o file system can cause security violations (depending on the paranoia level set by the 
a user of the browser). Try to create applets that do not depend on files at all, by 
using servers to hold shared information. If that’s impossible, limit your applet’s 
1/0 to asingle file or directory to which the user can easily assign file access permis- 
sion. (Stand-alone J ava programs have none of these problems, of course.) 


You also can create the stream from a previously opened file descriptor: 


int fd 
InputStream s 


openInputFileInTraditionalUNIXWays() ; 

new FileInputStream(fd) ; 

In either case, because it’s based on an actual (finite length) file, the input stream created can 
implement available() precisely and can skip) likea champ (just as ByteArrayInputStream 
can, by the way). In addition, FiteInputStream knows a few more tricks: 
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FileInputStream aFIS = new FileInputStream("aFileName") ; 
int myFD = aFIS.getFD(); 


/* aFIS.finalize(); */ // will call close() when automatically called by GC 


Tip: To call the new methods, you must declare the stream variable arts to be of 
type FileInputStream, because plain inputstreamS don’t know about then. 


Thefirst is obvious: getFo() returns the file descriptor of thefileon which the stream is based. 
The second, though, is an interesting shortcut that allows you to create FileInputStreamS 
without worrying about closing them later. FileInputstream’Simplementation of finalize(), 
aprotected method, closesthestream. U nlikein theprevious contrived examplein comments, 
you almost never can nor should call a finalize() method directly. T he garbage collector calls 
it after noticing that the stream is no longer in use, but before actually destroying the stream. 
T hus, you can go merrily along using thestream, never closingit, and all will bewell. T hesystem 
takes care of closing it (eventually). 


You can get away with this because streams based on files tie up very few resources, and these 
resources cannot beaccidentally reused before garbage collection (these werethe things worried 
about in thepreviousdiscussion of finalization and close()). Of course, if you werealso writing 
to thefile, you would have to be more careful. (Reopening thefiletoo soon after writing might 
make it appear in an inconsistent state because the finalize()—and thus the close()— 

might not have happened yet). J ust because you don’t have to close the stream doesn’t mean 
you might not want to do so anyway. For clarity, or if you don’t know precisely what type of 
an InputStream you were handed, you might choose to call close) yourself. 


Filter! nputStream 


This “abstract” class simply provides a “pass-through” for all the standard methods of 
InputStream. It holdsinside itself another stream, by definition one further “down” the chain 
of filters, to which it forwards all method calls. It implements nothing new but allows itself to 
be nested: 


InputStream s 

FilterInputStream s1 
FilterInputStream s2 
FilterInputStream s3 


getAnInputStreamFromSomewhere() ; 
new FilterInputStream(s) ; 
new FilterInputStream(s1) ; 
new FilterInputStream(s2) ; 


. S3.read() ... 
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Whenever a read is performed on the filtered stream sa, it passes along the request to s2; then 
s2doesthesameto s1, and finally s isasked to providethebytes. SubclassesofFilterInputStream 
will, of course, do some nontrivial processing of the bytes as they flow past. T he rather verbose 
form of “chaining” in the previous example can be made more elegant: 


s3 = new FilterInputStream(new FilterInputStream(new FilterInputStream(s) )); 


You should use this idiom in your code whenever you can. It clearly expresses the nesting of 
chained filters, and can easily be parsed and “read aloud” by starting at theinnermost stream s 
and reading outward— each filter stream applying to the one within— until you reach the 
outermost stream s3. 


Note: FilterInputStream is called “abstract,” rather than abstract, because it is not 
actually declared to be abstract. T his means that, as useless as they are, you can 
create instances of FilterInputStream directly. The same will hold for its output 
stream “brother” class, described later today. 


N ow let’s examine each of the subclasses of FilterInputStream in turn. 


B uffered!I nputStream 

This is one of the most valuable of all streams. It implements the full complement of 
InputStream’s methods, but it doesso by using a buffered array of bytes that acts as a cache for 
futurereading. T hisdecouplestherateand thesizeofthe“chunks” you’rereadingfrom themore 
regular, larger block sizes in which streams are most efficiently read (from, for example, 
peripheral devices, filesin the file system, or the network). It also allows smart streams to read 
ahead when they expect that you will want more data soon. 


Becausethebuffering of But feredInputstream isso valuable, and it’salso theonly classto handle 
mark() and reset() properly, you might wish that every input stream could somehow shareits 
valuablecapabilities. Normally, becausethosestream classesdo not implement them, you would 
be out of luck. Fortunately, you already saw a way that filter streams can wrap themselves 
“around” other streams. Suppose that you would like a buffered FileInputStream that can 
handle marking and resetting correctly. Et voila: 


InputStream s = new BufferedInputStream(new FileInputStream("foo") ); 
You have a buffered input stream based on the file “foo” that can mark() and reset(). 


N ow you can begin to seethe power of nesting streams. Any capability provided by afilter input 
stream (or output stream, as you'll see soon) can be used by any other, basic stream via nesting. 
Of course, any combination of these capabilities, and in any order, can beaseasily accomplished 
by nesting the filter streams themselves. 


D atal nputStream 

All themethods that instances of this class understand are defined in aseparateinterface, which 
both pataInputStream and RandomAccessFile (another class in java.io) implement. This 
interface is general-purpose enough that you might want to use it yourself in the classes you 
create. It is called pataInput. 


The D atal nput Interface 

W hen you begin using streams to any degree, you'll quickly discover that byte streams are not 
areally helpful format into which to forceall data. In particular, the primitive types of the] ava 
languageembody arather nice way of looking at data, but with the streams you’vebeen defining 
thus far in this book, you could not read data of these types. T he D atalnput interface specifies 
ahigher-level set of methods that, when used for both reading and writing, can support amore 
complex, typed stream of data. H ere are the set of methods this interface defines: 


void readFully(byte[] buffer) throws IOException; 
void readFully(byte[] buffer, int offset, int length) throws IOException; 
int  skipBytes(int n) throws IOException; 
boolean readBoolean() throws IOException; 
byte readByte() throws IOException; 
int readUnsignedByte() throws IOException; 
short readShort () throws IOException; 
int readUnsignedShort() throws IOException; 
char readChar () throws IOException; 
int readInt() throws IOException; 
long readLong() throws IOException; 
float readFloat () throws IOException; 
double readDouble() throws IOException; 
String readLine() throws IOException; 
String readUTF () throws IOException; 


Thefirst three methods are simply new names for skip() and the two forms of read() you’ve 
seen previously. Each of the next ten methods reads in a primitive type, or its unsigned 
counterpart (useful for using every bit efficiently in abinary stream). T heselatter methods must 
return an integer of a wider size than you might think; because integers are signed in J ava, the 
unsigned value does not fit in anything smaller. T he final two methods read anewline(‘\r', 
'\n', OF "\r\n") terminated string of characters from the stream— the first in ASCII, and the 
second in U nicode. 


N ow that you know what theinterface that pataInputstream implements looks like, let’s see it 
in action: 


DataInputStream s = new DataInputStream(getNumericInputStream() ) ; 
long size = s.readLong(); // the number of items in the stream 


while (size-- > 0) 
if (s.readBoolean()) { // should I process this item? 
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int anInteger 
int magicBitFlags 
double aDouble 


s.readiInt(); 
s.readUnsignedShort() ; 
s.readDouble(); 


if sole aaaae st & 0100000) != 0) { 
: // high bit set, do something special 


} 
. // process anInteger and aDouble 
} 
} 
Because the class implements an interface for all its methods, you can also use the following 
interface: 


DataInput d = new DataInputStream(new FileInputStream("anything") ) ; 
String line; 


while ((line = d.readLine()) != null) { 
Par // process the line 


} 


The EOFE xception 

One final point about most of pataInputstream’s methods: when the end of the stream is 
reached, they throw an EOFException. T his is tremendously useful and, in fact, allows you to 
rewrite all the kludgy uses of -1 you saw earlier today in a much nicer fashion: 


DataInputStream s = new DataInputStream(getAnInputStreamFromSomewhere() ) ; 


try { 
while (true) { 
byte b = (byte) s.readByte(); 
. : // process the byte b 


} 
} catch (EOFException e) { 
: : // reached end of stream 


} 
T his works just as well for all but the last two of the read methods of pataInputStream. 


| Caution: skipBytes() does nothing at all on end of stream, readLine() returns 
null, and readuTF() might throw a UTFDataFormatException, if it notices the 
a problem at all. 


LineNumberl nputStream 
In an editor or a debugger, line numbering is crucial. T o add this valuable capability to your 
programs, usethefilter stream LineNumberInputStream, which keepstrack of linenumbersasits 
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stream “flows through” it. It’s even smart enough to renember aline number and later restore 
it, during amark() and reset(). You might use this class as follows: 


LineNumberInputStream aLNIS; 
aLNIS = new LineNumberInputStream(new FileInputStream("source") ) ; 


DataInputStream s = new DataInputStream(aLNIS) ; 
String line; 


while ((line = s.readLine()) != null) { 
ee. Srv // process the line 
System.out.printin("Did line number: " + aLNIS.getLineNumber()); 


H ere, two filter streams are nested around the FiletnputStream actually providing the data— 

thefirst to read linesoneat atimeand thesecond to keep track of thelinenumbers of theselines 
as they go by. You must explicitly nametheintermediatefilter stream, aLnrs, becauseif you did 
not, you couldn't call getLinenumber() later. N ote that if you invert the order of the nested 
streams, reading from the bataInputStream doesnot cause the LineNumberInputStream to “see” 
the lines. 


You must put any filter streams acting as “monitors” in the middle of the chain and “pull” the 
data from the outermost filter stream so that the data will passthrough each of the monitorsin 
turn. In thesameway, buffering should occur asfar insidethe chain as possible, becauseit won't 
be ableto do itsjob properly unless most of the streams that need buffering come after it in the 
flow. For example, here's a doubly silly order: 


new BufferedInputStream(new LineNumberInputStream( 
new DataInputStream(new FileInputStream("foo") ) 


and here’s a much better order: 


new DataInputStream(new LineNumberInputStream( 

new BufferedInputStream(new FileInputStream("foo")) ; 
LineNumberInputStreamS Can also be told to setLinenumber(), for those few times when you 
know more than they do. 


Pushbackl nputStream 

T hefilter stream class PushbackInputStreamiScommonly used in parsers, to “push back” asingle 
character in theinput (after reading it) while trying to determine what to do next— asimplified 
version of the mark() and reset() utility you learned about earlier. Its only addition to the 
standard set of Inputstream methods is unread(), which as you might guess, pretends that it 
never read the byte passed in asits argument, and then gives that byte back as the return value 
of the next read(). 


The following isa simple implementation of readLine() using this class: 


public class SimpleLineReader { 
private FilterInputStream s; 
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public SimpleLineReader(InputStream anIS) { 
s = new DataInputStream(anIS) ; 


} 
// other read() methods using stream s 


public String readLine() throws IOException { 
char[] buffer = new char[100]; 
int offset = Q; 
byte thisByte; 


try { 
loop: while (offset < buffer.length) { 
switch (thisByte = (byte) s.read()) { 

case '\n': 
break loop; 

case '\r': 
byte nextByte = (byte) s.read(); 
if (nextByte != '\n') { 


if (!(s instanceof PushbackInputStream)) { 
s = new PushbackInputStream(s) ; 


} 
((PushbackInputStream) s).unread(nextByte) ; 
} 


break loop; 

default: 
buffer[offsett+] = (char) thisByte; 
break; 


} 


} 
} catch (EOFException e) { 
if (offset == Q) 
return null; 


} 
return String.copyValueOf (buffer, @, offset); 


} 


T his demonstrates numerous things. For the purpose of this example, readLine() is restricted 
to reading the first 100 characters of the line. In this respect, it demonstrates how not to write 
a general-purpose line processor (you should be able to read any size line). It also raninds you 
how to break Out of an outer loop, and how to producea string from an array of characters (in 
this case, from a “slice” of the array of characters). T his example also includes standard uses of 
InputStream’S read() for reading bytes oneat atime, and of determining the end of the stream 
by enclosing it in a pataInputStream and catching EOFException. 


O neof the more unusual aspects of the exampleis the way PushbackInputStream is used. T 0 be 
sure that '\n' isignored following '\r' you haveto “look ahead” one character; but if it is not 
a'\n', you must push back that character. Look at thenext two linesasif you didn’t know much 
about the stream s. T he general technique used isinstructive. First, you seewhether s is already 
an instanceof somekind of PushbackInputStream. If So, youcan simply useit. If not, you enclose 


the current stream (whatever it is) inside a new PushbackInputStream and use this new stream. 
N ow, let’s jump back into the context of the example. 


T helinefollowing wantsto call themethod unreaa(). Theproblem isthat s hasa“compiletime 
type” of FilterInputStream, and thus doesn’t understand that method. T heprevious two lines 
have guaranteed, however, that the run-time type of the stream in s is PushbackInputStream, SO 
you can safely cast it to that type and then safely call unread(). 


Note: T his example was done in an unusual way for demonstration purposes. You 
could have simply declared a pushbackInputStream variable and always enclosed the 
DataInputStream in it. (Conversely, simpleLineReader’s constructor could have 
checked whether its argument was already of the right class, the way 
PushbackInputStream did, before creating anew DataInputStream.) T he interesting 
thing about this approach of “wrapping aclass only when needed” is that it works 
for any InputStream that you hand it, and it does additional work only if it needs 
to. Both of these are good general design principles. 


All thesubclasses of FilterInputStream havenow been described. It’stimeto return to thedirect 
subclasses of InputStream. 


Piped!I nputStream 


Thisclass, along with its “brother” class PipedoutputStream, are covered later today (they need 
to be understood and demonstrated together). For now, all you need to Know is that together 
they create a simple, two-way communication conduit between threads. 


Sequencel nputStream 


Suppose you have two separate streams, and you would like to make a composite stream that 
consists of one stream followed by the other (like appending two strings together). This is 
exactly what sequenceInputStream was created for: 


InputStream s1 
InputStream s2 


new FileInputStream("theFirstPart") ; 
new FileInputStream("theRest") ; 


InputStream s = new SequenceInputStream(s1, s2); 
. S.read() ... // reads from each stream in turn 


You could have “faked” this example by reading each filein turn— but what if you had to hand 
the composite stream s to some other method that was expecting only a single Inputstream? 
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H ere’san example (usings) that linenumbersthetwo previousfiles with acommon numbering 
scheme: 


LineNumberInputStream aLNIS = new LineNumberInputStream(s) ; 


. aLNIS.getLineNumber() ... 


Note: Stringing together streams this way is especially useful when the streams are 
of unknown length and origin, and were just handed to you by someone else. 


W hat if you want to string together more than two streams? You could try the following: 


Vector v = new Vector(); 

se // set up all the streams and add each to the Vector 

InputStream s1 = new SequenceInputStream(v.elementAt(0), v.elementAt(1)); 
InputStream s2 new SequenceInputStream(s1, v.elementAt (2) ) ; 

InputStream s3 new SequenceInputStream(s2, v.elementAt(3) ) ; 


Note: A vector iS a growable array of objects that can be filled, referenced (with 
elementAt()) and enumerated. 


H owever, it’s much easier to use a different constructor that sequenceInputStream provides: 
InputStream s = new SequenceInputStream(v.elements()) ; 


Ittakesan enumeration of all thesequences you wish to combineand returnsasinglestream that 
reads through the data of each in turn. 


StringB ufferl nputStream 


StringBufferInputStream IS exactly like ByteArrayInputStream, but instead of being based on 
a byte array, it’s based on an array of characters (a string): 


String buffer 
InputStream s 


"Now is the time for all good men to come..."; 
new StringBufferInputStream(buffer) ; 


All comments that were made about ByteArrayInputStream apply here as wall. (See the earlier 
section on that class.) 
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Note: stringBufferInputStream iS a bit of a misnomer, because this input stream is 
actually based on a string. It should really be called stringInputStream. 


Output Streams 


Output streams are, in almost every case, paired with a “brother” Inputstream that you've 
already learned. If an tnputstream performs a certain operation, the “brother” outputstream 
performs the inverse operation. You'll see more of what this means soon. 


T he abstract Class O utputStream 


OutputStream iS the abstract class that defines the fundamental ways in which a source 
(producer) writes a stream of bytes to some destination. T heidentity of thedestination, and the 
manner of the transport and storage of the bytes, is irrelevant. When using an output stream, 
you are the source of those bytes, and that’s all you need to know. 


write() 

The most important method to the producer of an output stream is the one that writes bytes 
to the destination. This method, write), Comes in many flavors, each demonstrated in an 
example below. 


Note: Every one of these write) methods is defined to “block” (wait) until all 
the output requested has been written. You don’t need to worry about this 
limitation— see the note under InputStream’S read() method if you don’t 
remember why. 


OutputStream s 
byte[] buffer 


getAnOutputStreamFromSomewhere() ; 
new byte[1024]; // any size will do 


fillInData(buffer) ; // the data we want to output 
s.write(buffer) ; 


You also can write a “slice” of your buffer by specifying the offset into the buffer, and thelength 
desired, as arguments to write(): 


s.write(buffer, 100, 300); 
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T his writes out bytes 100 through 399 and behaves otherwise exactly the same as the previous 
write() method. In fact, in thecurrent release, thedefault implementation of theformer version 
of write() uses the latter: 


public void write(byte[] buffer) throws IOException { 
write(buffer, 0, buffer.length) ; 
} 


Finally, you can write out bytes one at a time: 


while (thereAreMoreBytesToOutput()) { 
byte b = getNextByteForOutput(); 


s.write(b) ; 


flush() 


Becauseyou don’t know what an output stream isconnected to, you might berequired to “flush” 
your output through some buffered cache to get it to be written (in atimely manne, or at all). 
OutputStream’s version of this method does nothing, but it is expected that subclasses that 
requireflushing (for example, BufferedoutputStreamand Printstream) will overridethisversion 
to do something nontrivial. 


close() 


Just likefor an Inputstream, you should (usually) explicitly closedown an outputstream so that 
it can release any resourcesit may havereserved on your behalf. (All thesamenotesand examples 
from InputStream’Sclose() method apply here, with theprefix mn reolaced everywhere by out.) 


All output streams descend from the abstract class outputStream. All share the previous few 
methods in common. 


B yteArrayO utputStream 


Theinverse of ByteArrayInputStream, which creates an input stream from an array of bytes, is 
ByteArrayOutputStream, which directs an output stream into an array of bytes: 


OutputStream s = new ByteArrayOutputStream() ; 

s.write(123); 

The size of the (internal) byte array grows as needed to store a stream of any length. You can 
provide an initial capacity as an aid to the class, if you like 


OutputStream s = new ByteArrayOutputStream(1024 * 1024); // 1 Megabyte 
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Note: You've just seen your first examples of the creation of an output stream. 
T hese new streams were attached to the simplest of all possible destinations of data, 
an array of bytes in the memory of the local computer. 


OncethesyteArrayoutputStreams hasbeen “filled,” it can beoutput to another output stream: 


OutputStream anotherOutputStream = getTheOtherOutputStream() ; 
ByteArrayOutputStream s = new ByteArrayOutputStream() ; 


fillWithUsefulData(s) ; 
s.writeTo(anotherOutputStream) ; 


It also can be extracted as a byte array or converted to a string: 


byte[] buffer = s.toByteArray(); 
String bufferString = s.toString(); 
String bufferUnicodeString = s.toString(upperByteValue) ; 


Note: T he last method allows you to “fake” U nicode (16-bit) characters by filling 
in their lower bytes with ASCII and then specifying acommon upper byte (usually 
a) to create aU nicode string result. 


ByteArrayOutputStreams have two utility methods: one simply returns the current number of 
bytes stored in the internal byte array, and the other resets the array so that the stream can be 
rewritten from the beginning: 


int sizeOfMyByteArray = s.size(); 


s.reset(); // s.size() would now return 0 
s.write(123); 


FileO utputStream 


O neof the most common uses of streams isto attach them to filesin the file system. H ere, for 
example, isthe creation of such an output stream on aUNIX system: 


OutputStream s = new FileOutputStream("/some/path/and/fileName") ; 


| Caution: Applets attempting to open, read, or write streams based on filesin the 
file system can cause security violations. See the note under FileInputstream for 
a more details. 
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You also can create the stream from a previously opened file descriptor: 


int fd 
OutputStream s 


openOutputFileInTraditionalUNIXWays() ; 
new FileOutputStream(fd) ; 


FileOutputStream is the inverse of FileInputStream, and it knows the same tricks: 


FileOutputStream aFOS = new FileOutputStream("aFileName" ) ; 
int myFD = aFOS.getFD(); 


/* aFOS.finalize(); */ // will call close() when automatically called by GC 


Note: T 0 call the new methods, you must declare the stream variable aFos to be of 
type@ FileoutputStream, because plain outputstreams don’t know about them. 


The first is obvious. getFo() simply returns the file descriptor for the file on which the stream 
is based. T he second, commented, contrived call to tinalize() isthereto remind you that you 
don’t have to worry about closing the stream— it is done for you automatically. (See the 
discussion under FileInputstream for more.) 


FilterO utputStream 


This “abstract” class simply provides a “pass-through” for all the standard methods of 
OutputStream. It holdsinsideitself another stream, by definition onefurther “down” the chain 
of filters, to which it forwards all method calls. It implements nothing new but allows itself to 
be nested: 

OutputStream Ss 
FilterOutputStream s1 


FilterOutputStream s2 
FilterOutputStream s3 


getAnOutputStreamFromSomewhere() ; 
new FilterOutputStream(s) ; 
new FilterOutputStream(s1) ; 
new FilterOutputStream(s2) ; 


. s8.write(123) ... 


Whenever awriteis performed on thefiltered stream s3, it passes along the request to s2. Then 
s2doesthesameto s1, and finallysisasked to output thebytes. SubclassesofrilteroutputStream, 
of course, do somenontrivial processing of the bytes as they flow past. T his chain can betightly 
nested— see its “brother” class, FilterInputStream for more. 


N ow let’s examine each of the subclasses of FilteroutputStream in turn. 


B ufferedO utputStream 


BufferedOutputStream isoneof themost valuableof all streams. All it doesisimplement thefull 
complement of outputstream’s methods, but it does so by using a buffered array of bytes that 
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acts as a cache for writing. T his decouples the rate and the size of the “chunks” you're writing 
from the more regular, larger block sizes in which streams are most efficiently written (to 
peripheral devices, files in the file system, or the network, for example). 


BufferedOutputStream is one of two classes in the J ava library to implement f1ush(), which 
pushes the bytes you've written through the buffer and out the other side. Because buffering is 
so valuable, you might wish that every output stream could somehow be buffered. Fortunately, 
you can surround any output stream in such a way as to achieve just that: 


OutputStream s = new BufferedOutputStream(new FileOutputStream("foo")); 
You now havea buffered output stream based on the file “foo” that can be f1ush()ed. 


Just as for filter input streams, any capability provided by a filter output stream can be used by 
any other basic stream via nesting and any combination of these capabilities, in any order, can 
be as easily accomplished by nesting the filter streams themselves. 


D ataO utputStream 

All the methods that instances of this class understand are defined in aseparate interface, which 
both pataoutputStream and RandomAccessFile implement. This interface is general-purpose 
enough that you might want use it yourself in the classes you create. It is called pataoutput. 


The D ataO utput Interface 

In cooperation with its “brother” inverse interface, pataInput, DataOutput provides a higher- 
level, typed-stream approach to thereading and writing of data. Rather than dealing with bytes, 
this interface deals with writing the primitive types of the J ava language directly: 


void write(int i) throws IOException; 
void write(byte[] buffer) throws IOException; 
void write(byte[] buffer, int offset, int length) throws IOException; 


void writeBoolean(boolean b) throws IOException; 


void writeByte(int i) throws IOException; 
void writeShort(int i) throws IOException; 
void writeChar(int i) throws IOException; 
void writeInt(int i) throws IOException; 
void writeLong(long 1) throws IOException; 
void writeFloat(float f) throws IOException; 


void writeDouble(double d) throws IOException; 

void writeBytes(String s) throws IOException; 

void writeChars(String s) throws IOException; 

void writeUTF(String s) throws IOException; 

M ost of these methods have counterparts in the interface pataInput. 

T hefirst three methods mirror the three forms of write() you saw previously. Each of thenext 
eight methods write out a primitive type. T he final three methods write out a string of bytes or 
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characters to the stream: the first one as 8-bit bytes; the second, as 16-bit U nicode characters; 
and the last, as a special U nicode stream (readable by D atal nput’s readuTF () ). 


Note: T he unsigned read methods in patarInput have no counterparts here. You 
can write out the data they need via pataoutput’s signed methods because they 
accept int arguments and also because they write out the correct number of bits for 
the unsigned integer of a given size as a side effect of writing out the signed integer 
of that same size. It isthe method that reads this integer that must interpret the 
sign bit correctly; the writer’s job is easy. 


N ow that you know what the interface that pataoutputstream implements looks like, let's see 
it in action: 


DataOutputStream s 
long size 


new DataOutputStream(getNumericOutputStream() ) ; 
getNumberOfItemsInNumericStream() ; 


s.writeLong(size) ; 


for (int i= 0; i < size; ++i) { 
if (shouldProcessNumber(i)) { 
s.writeBoolean(true) ; // should process this item 
s.writeInt(theIntegerForItemNumber (i) ); 
s.writeShort (theMagicBitFlagsForItemNumber (i) ); 
s.writeDouble(theDoubleForItemNumber (i) ); 
} else 
s.writeBoolean(false) ; 
} 
T hisisthe exact inverse of the examplethat was given for patarnput. T ogether, they form apair 
that can communicate a particular array of structured primitive types across any stream (or 
“transport layer”). Use this pair as a jumping-off point whenever you need to do something 


similar. 


In addition to the interface above, the class itself implements one (self-explanatory) utility 
method: 


int theNumberOfBytesWrittenSoFar = s.size(); 


Processing a File 

Oneof the most common idiomsin filel/O isto open afile, read and process it line-by-line, 
and output it again to another file. H ere’s a prototypical example of how that would be done 
in Java: 
DataInput aDI 


DataOutput aDO 
String line; 


new DataInputStream(new FileInputStream("source") ); 
new DataOutputStream(new FileOutputStream("dest")); 


while ((line = aDI.readLine()) != null) { 
StringBuffer modifiedLine = new StringBuffer (line) ; 


// process modifiedLine in place 
abo. writeBytes(modifiedLine. toString()); 


} 
aDI.close(); 
aDO.close(); 


If you want to process it byte by-byte, use this: 


try { 
while (true) { 
byte b = (byte) aDI.readByte(); 


// process b in place 
abo. writeByte(b) ; 


} 

} finally { 
aDI.close(); 
aDO.close(); 

} 


H ere’s a cute two-liner that just copies the file 


try { while (true) aDO.writeByte(aDI.readByte()); } 
finally { aDI.close(); aDO.close(); } 


| Caution: M any of the examples in today’s lesson (and the last two) assume that 
a they appear inside a method that has 1oException in its throws clause, so they don’t 
a have to “worry” about catching those exceptions and handling them more reason- 
ably. Your code should be alittle less cavalier. 


PrintStream 
You may not realizeit, but you’realready intimately familiar with the use of two methods of the 
PrintStream Class. T hat’s because whenever you use these method calls: 


System.out.print(. . .) 
System.out.printin(. . .) 


you areactually using aprintstreaminstancelocated in thesystem’sclassvariableout to perform 
the output. system.err iS alSO a PrintStream, aNd System. in iS AN InputStream. 


Note: On UNIX systems, these three streams will be attached to standard output, 
standard error, and standard input. 
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PrintStream iS uniquely an output stream class (it has no “brother”). Because it is usually 
attached to a screen output device of some kind, it provides an implementation of f1ush(). It 
also provides the familiar close() and write() methods, as well as a plethora of choices for 
outputting the primitive types and strings of J ava: 


public void write(int b); 

public void write(byte[] buffer, int offset, int length); 
public void flush(); 

public void close(); 


public void print(Object 0); 
public void print(String s); 
public void print(char[] buffer); 
public void print(char c); 

public void print(int i); 

public void print(long 1); 

public void print(float f); 

public void print(double d); 
public void print(boolean b); 


public void println(Object 0); 
public void printin(String s); 
public void println(char[] buffer); 
public void printlin(char c); 

public void println(int i); 

public void println(long 1); 

public void println(float f); 

public void println(double d); 
public void println(boolean b); 


public void println(); // output a blank line 

PrintStream Can also be wrapped around any output stream, just like a filter class: 
PrintStream s = PrintStream(new FileOutputStream("foo")); 
s.printin("Here's the first line of text in the file foo."); 


If you provideasecond argument to theconstructor forPrintstream, it isaboolean that specifies 
whether the stream should auto-flush. If true, af1ush() issent after each character is written 
(or for the three-argument form of write(), after awholegroup of characters has been written.) 


Here's a simple example program that operates like the UNIX command cat, taking the 
standard input, line-by-line, and outputting it to the standard output: 


import java.io.*; // the one time in the chapter we'll say this 


public class Cat { 
public static void main(String args[]) { 
DataInput d = new DataInputStream(System. in) ; 
String line; 


try { while ((line = d.readLine()) != null) 
System.out.printlin(line) ; 


} catch (IOException ignored) { } 


} 


PipedO utputStream 


Along with pipedinputstream, this pair of classes supports a UN1X-pipelike connection 
between two threads, implenenting all the careful synchronization that allows this sort of 
“shared queue” to operate safely. T o set up the connection: 


PipedInputStream sIn 
PipedOutputStream sOut 


PipedInputStream(); 
PipedOutputStream(sIn) ; 


O nethread writesto sout, and theother readsfrom sin. By setting up two such pairs, thethreads 
can communicate safely in both directions. 


R elated Classes 


The other classes and interfacesin java.io supplement the streams to providea complete !/O 
system. 


T herFite class abstracts “file” in aplatform-independent way. Given a filename, it can respond 
to queries about the type, status, and properties of a file or directory in the file system. 


A RandomAccessFileiscreated given afile, afilename, or afiledescriptor. It combinesin oneclass 
implementations of the pataInput and Dataoutput interfaces, both tuned for “random access” 
to afile in the file system. In addition to these interfaces, RandomAccessFile provides certain 
traditional UN IX-like facilities, such as seek()ing to arandom point in the file. 


Finally, the streamTokenizer Classtakesan input stream and produces a sequence of tokens. By 
overriding its various methods in your own subclasses, you can create powerful lexical parsers. 


You can learn more about any and all of these classes from the full (online) API descriptionsin 
your J ava release. 


Summary 


T oday, you learned about thegeneral ideaof streamsand met input streamsbased on bytearrays, 
files, pipes, sequences of other streams, and string buffers, as well as input filters for buffering, 
typing data, line numbering, and pushing-back characters. 


You also met theanalogous “brother” output streamsfor bytearrays, files, and pipes, and output 
filters for buffering and typing data, and the unique output filter used for printing. 
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Along theway, you becamefamiliar with thefundamental methodsall streamsunderstand (such 
a read() and write()), aswell astheuniquemethodsmany streams add to this repertoire. You 
learned about catching 10Exceptions— especially the most useful of then, EoFException. 


Finally, thetwice-useful pataInput and Dataoutput interfacesformed theheart ofrandomAccessFile, 
one of the several utility classes that round out J ava’s1/O facilities. 


Java streams provide a powerful base on which you can build multithreaded, streaming 
interfaces of themost complex kinds, and the programs(such asH ot] ava) tointerpretthem. T he 
higher-level Internet protocols and services of the future that your applets can build upon this 
base are really limited only by your imagination. 


Q&A 


Q_Inan early reaa() example, you did something with the variable byteorminus1 
that seemed a little clumsy. Isn’t there a better way? If not, why recommend the 
cast later? 


A Y6, thereis something alittle odd about those statements. You might be tempted to 
try something like this instead: 


while ((b = (byte) s.read()) != -1) { 
// process the byte b 
} 


The problem with this short-cut occurs when read() returns the value oxFF (0377). 
Since this value is signed-extended before the test gets executed, it will appear to be 
identical to the integer value -1 that indicates end of stream. O nly saving that value in 
a separate integer variable, and then casting it later, will accomplish the desired result. 
The cast to byte is recommended in the note for orthogonal reasons— storing integer 
values in correctly sized variables is always good style (and besides, read ) really 
should be returning something of byte size here and throwing an exception for end of 
stream). 


Q What input streams in java.io actually implement mark(), reset(), and 
markSupported()? 


A InputStream itself does— and in their default implementations, marksupported() 
returns false, mark() does nothing, and reset() throws an exception. The only input 
stream in the current release that correctly supports marking is BufferedInputStream, 
which overrides these defaults. LineNumberInputStream actually implements mark () 
and reset(), but in the current release, it doesn’t answer markSupported() correctly, so 
it looks as if it does not. 


p> Oo 


pe) 


Why is availabie() useful, if it sometimes gives the wrong answer? 


First, for many streams, it gives the right answer. Second, for some network streams, 
its implementation might be sending a special query to discover some information you 
couldn’t get any other way (for example, the size of a file being transferred by ftp). If 
you were displaying a “progress bar” for network or file transfers, for example, 
available() would often give you the total size of the transfer, and if it did not— 
usually by returning a— it would be obvious to you (and your users). 

W hat’s a good example use of the pataInput/pataoutput pair of interfaces? 
Onecommon use of such a pair is when objects want to “pickle” themselves for 
storage or movement over a network. Each object implements read and write methods 
using these interfaces, effectively converting itself to a stream that can later be recon- 
stituted “on the other end” into a copy of the original object. 
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Today, you'll learn all the reasons you might (or might not) want to write native methodsin 
Java, about all of J ava’s built-in optimizations, and about the tricks you can use to make your 
programs faster. You'll also learn the procedure for creating, making headers and stubs for, and 
linking native methods into a dynamically loadable library. 


Let's begin, however, with the reasons that you might want to implement native methods in 
the first place. 


T here are only two reasons that you might need to declare some of your methodSnative, that 
is, implemented by a language other than J ava. 


The first, and by far the best reason to do so, is because you need to utilize a special capability 
of your computer or operating system that the] avaclasslibrary doesnot already providefor you. 
Such capabilities include interfacing to new peripheral devices or plug-in cards, accessing a 
different type of networking, or using aunique, but valuablefeatureof your particular operating 
system. T wo more concrete examples are acquiring real-time audio input from a microphone 
or using 3D “accelerator” hardwarein a 3D library. N either of these is provided to you by the 
current Java environment, so you must implement them outside J ava, in some other language 
(currently C or any language that can link with C). 


T hesecond, and often illusory reason to implement native methods, isspeed— illusory, because 
you rarely need theraw speeds gained by thisapproach. It’s even morerareto not beableto gain 
that speed-up in other ways (as you'll see later today). U sing native methods in this case takes 
advantage of the fact that, at present, the] ava release does not perform as well as, for example, 
an optimized C program on many tasks. For thosetasks, you can writethe “needsto befast” part 
(critical, inner loops, for example) in C, and still use a larger J ava shell of classes to hide this 
“trick” from your users. In fact, the] avaclasslibrary usesthisapproach for certain critical system 
Classes to raisethe overall level of efficiency in thesysten. Asauser of the] avaenvironment, you 
don’t even know (or see) any results of this (except, perhaps, a few classes or methods that are 
final that might not be otherwise). 


Disadvantages of native Methods 


Once you decide you'd liketo, or must, us@native methodsin your program, this choice costs 
you dearly. Although you gain theadvantages mentioned earlier, you losethe portability of your 
Java code. 


Before, you had a program (or applet) that could travel to any Java environment in the world, 
now and forever. Any new architectures created— or new operating systems written— were 
irrelevant to your code. All it required was that the (tiny) J ava Virtual M achine (or a browser 
that had oneinsideit) beavailable, and it could run anywhere, anytime— now and in thefuture. 
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N ow, however, you’ve created a library of native code that must be linked with your program 
to makeit work properly. T hefirst thing you loseisthe ability to “travel” asan applet; you simply 
can't be one! N o J ava-aware browser currently in existence allows native codeto beloaded with 
an applet, for security reasons (and theseare good reasons). T he} ava team has struggled to place 
as much as possibleinto the java packages because they arethe only environment you can count 
on asan applet. (The sun packages, shipped primarily for use with stand-alone] ava programs, 
are not always available to applets.) 


Note: Actually, any classes that anyone writes without native code should be able to 
be loaded with an applet, as long as they depend only on the java packages. 
Unfortunately, many of the sun packages contain classes that mus use native code 
to provide crucial, missing functionality from the java packages. All these missing 
pieces, and some additional multimedia and sound capabilities, will be added to the 
java packages in the future. (T his has been informally promised in discussions |’ve 
had with the] ava team.) 


Losing the ability to travel anywhere across the N et, into any browser written now or in the 
future, isbad enough. W hat’s worse, now that you can’t bean applet, you have further limited 
yourself to only thosemachinesthat havehad the} avaVirtual M achineported to their operating 
system. (Applets automatically benefit from the wide number of machines and operating 
systems that any J ava-aware browser is ported to, but now you do not.) 


Even worse, you have assumed something about that machine and operating system by the 
implementation of your native methods. T his often means that you have to write different 
sourcecodefor some (or all) of themachinesand operating systemson which you want to beable 
to run. You’realready forced, by using native methods, to producea separate binary library for 
every machine and operating system pair in the world (or at least, wherever you plan to run), 
and you must continueto do so forever. If changing thesourceisalso necessary, you can see that 
this is not a pleasant situation for you and your J ava program. 


T he Illusion of R equired E fficiency 


If, even after the previous discussion, you mus usenative methods anyway, there’shelp for you 
later in today’s lesson— but what if you’re still thinking you need to use them for efficiency 
reasons? 


You arein agrand tradition of programmersthroughout the (relatively few) ages of computing. 
It is exciting, and intellectually challenging, to program with constraints. If you believe 
efficiency isalways required, it makes your job alittle moreinteresting— you get to consider all 
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sorts of baroque ways to accomplish tasks, because it is the efficient way to do it. | myself was 
caught up in this euphoria of creativity when | first began programming, but it is creativity 
misapplied. 


W hen you design your program, all that energy and creativity should be directed at the design 
of atight, concise, minimal set of classes and methods that are maximally general, abstract, and 
reusable. (If you think that is easy, look around for a few years and see how bad most software 
is.) If you spend most of your programmingtimeon thinking and rethinking thesefundamental 
goals and how to achieve them, you are preparing for the future. A future where software is 
assembled asneeded from small componentsswimmingin aseaof network facilities, and anyone 
can write a component seen by millions (and reused in their programs) in minutes. If, instead, 
you spend your energy worrying about the speed your software will run right now on some 
computer, you will beirrelevant after the 18 to 36 monthsit will takehardwareto befast enough 
to hide that minor inefficiency in your program. 


Am | saying that you should ignore efficiency altogether? Of course not! Some of the great 
algorithms of computer science deal with solving hard or “impossible” problems in reasonable 
amounts of time— and writing your programs carelessly can lead to remarkably slow results. 
This, however, can as easily lead to incorrect, fragile, or nonreusable results. If you achieve all 
those other goals first, the resulting software will be clean, will naturally reflect the structure of 
the problem you're trying to solve, and thus will be amenable to “speeding up” later. 


Note: T here are always cases where you must be fanatical about efficiency in many 
parts of a set of classes. T he] ava class library itself is such a case, as is anything that 
must run in real-time for some critical real-world application (such as flying a 
plane). Such applications are rare, however. 


W hen speaking of a new kind of programming that must soon emerge, Bill Joy, a 
founder at Sun, likes to invoke the four S’s of Java: small, simple, safe, and secure. 
The “feel” of the} ava language itself encourages the pursuit of clarity and the 
reduction of complexity. The intense pursuit of efficiency, which increases com- 
plexity and reduces clarity, is antithetical to these goals. 


Once you build a solid foundation, debug your classes, and your program (or applet) works as 
you'd likeit to, then it’stime to begin optimizing it. If it’sjust a user interface applet, you may 
need to do nothing at all. T he user is very slow compared to modern computers (and getting 
relatively slower every 18 months). T he odds are that your applet is already fast enough— but 
suppose it isn’t. 


Built-In O ptimizations 


Your next job isto seewhether your release supports turning on the “just-in-time” compiler, or 
using the java2c tool. 


The first of these is an experimental technology that, while a method’s bytecodes are running 
in the] avaVirtual M achine, translates each bytecode into thenative binary code equivalent for 
the local computer, and then keeps this native code around as a cache for the next time that 
method isrun. T his trick iscompletely transparent to the] ava code you write. You need know 
nothing about whether or not it’s being done— your codecan still “travel” anywhere, anytime. 
On any system with “just-in-time” technology in place, however, it runsalot faster. Experience 
with experimental versions of thistechnology shows that, after paying a small cost thefirst time 
a method is run, this technique can reach the speed of compiled C code. 


Note: M ore details on this technique, and the java2c tool, will be presented 
tomorrow. As of the beta release, neither of these tools are in the] ava environment, 
but both are expected in the final release. 


T he java2c translator takes a whole.classfile full of the bytecodes for aclass and translates then 
(all at once) into a portable C source code version. This version can then be compiled by a 
traditional C compiler on your computer to produceanative-method-likecached library of fast 
code. T his large cache of native code will be used whenever the class's methods are called, but 
only on thelocal computer. Your original J ava code can still travel asbytecodes and run on any 
other computer system. I f the virtual machine automatically takes these steos whenever it makes 
sense for a given class, this can be as transparent as the “just-in-time” technology. Experience 
with an experimental version of thistool showsthat fully optimized C performanceisachievable. 
(This is the best anyone can hope to do!) 


So you see, even without taking any further steps to optimize your program, you may discover 
that for your release of J ava (or for releases elsewhere or coming in the near future), your code 
isalready fast enough. If it isnot, ranember that the world craves speed. | avawill only get faster, 
thetoolswill only get better. Your codeistheonly permanent thingin thisnew world— it should 
be the best you can make it, with no compromises. 


Simple O ptimization Tricks 


Supposethat these technologies aren't available or don’t optimize your program far enough for 
your taste. You can profile your applet or program asit runs, to seein which methods it spends 
themost time. O nceyou know thiscrucial information, you can begin to maketargeted changes 
to your classes. 
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(and, presumably, the final release) the javaprof tool can “pretty-print” this 
information in amore readable format. (javaprof is not in the beta release— but try 
the latest J ava release’s documentation for details.) 


| Tip: Use java -prof ... to produce this profile information. In an early release 


Before you begin making optimizations, you also may want to save a copy of your 
“clean” classes. As soon as computer speeds allow it (or amajor rewrite necessitates 
it), you can revert to these classes, which embody the “best” implementation of 
your program. 


First, identify the crucial few methods that take most of the time (there are almost always just 
afew, and often just one that takeup themajority of your program’stime). | f they contain loops, 
examine theinner loops to see whether they: call methods that can be made tina1, call a group 
of methodsthat can becollapsed into asinglemethod, or create objectsthat can be reused rather 
than created anew each loop. 


If you notice that along chain of, for example, four or more method calls is needed to reach a 
destination method’s code, and this execution path is in one of the critical sections of the 
program, you can “short-circuit” directly to that destination method in the topmost method. 
This may require adding a new instance variable to reference the object for that method call 
directly. T his quite often violates layering or encapsulation constraints. T hisviolation, and any 
added complexity, is the price you pay for efficiency. 


If, after all these tricks (and the numerous others you should try that have been collected over 
the years into various programming books), your J ava code is still just too slow, you will have 
to use native methods after all. 


Writing native Methods 


For whatever reasons, you've decided to add native methodsto your program. You've already 
decided which methods need to be native, and in which classes, and you're rarin’ to go. 


First, on the} avaside, all you do is delete the method bodies (all the code between the brackets 
{ and } and thebrackets themselves) of each method you picked and replacethem with asingle 
semicolon (;). Then add the modifier native to the method's existing modifiers. Finally, add 
astatic (Class) initializer to each classthat now containsnative methodsto load thenativecode 
library you're about to build. (You can pick any name you like for thislibrary— details follow.) 
You're done! 
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T hat’s all you need to do in J avato specify anative method. Subclasses of any class containing 
your new native methodscan still overridethem, and thesenew methodsare called for instances 
of the new subclasses (just as you’d expect). 


Unfortunately, what needs to be donein your native language environment is not so simple. 


Note: T he following discussion assumes that C and UNIX are your language and 
environment. T his means that some of the steps may differ slightly on your actual 
system, but such differences will be outlined in the notes surrounding the native 
method documentation in your release (in the document called Implementing 

N ative M ethods in the alpha, but folded into the programmer’s tutorial in the 
beta). T he following discussion is purposely parallel to this documentation. 


The Example Class 


Imagine a version of the] ava environment that does not provide filel/O. Any Java program 
needing to use the file system would first have to write native methods to get access to the 
operating system primitives needed to do filel/O. 


T his example combines simplified versions of two actual J ava library classes, java.io.File and 
java.io.RandomAccessFile, into a single new Class, simpleFile: 


public class SimpleFile { 


public static final char separatorChar = '>'; 
protected String path; 
protected int fd; 


public SimpleFile(String s) { 
path = s; 
} 


public String getFileName() { 
int index = path.lastIndexOf(separatorChar) ; 


return (index < 0) ? path : path.substring(index + 1); 


} 


public String getPath() { 
return path; 


} 

public native boolean open(); 

public native void close(); 

public native int read(byte[] buffer, int length); 
public native int write(byte[] buffer, int length); 
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static { 
System.loadLibrary("simple"); // runs when class first loaded 


} 


Note: T he unusual separatorchar ('>') isused simply to demonstrate what an 
implementation might look like on some strange computer whose file system didn’t 
use any of the more common path separator conventions. Early Xerox computers 
used '>' aSa separator, and several existing computer systems still use strange 
separators today, so thisis not all that farfetched. 


SimpleFileS Can be created and used by other methods in the usual way: 


SimpleFile f = new SimpleFile(">some>path>and>fileName" ) ; 


-open(); 
-read(...); 
-write(...); 
-Close(); 


hhh 


= 


The first thing you notice about simp1eFile’s implementation is how unremarkable the first 
two-thirdsof its] avacodeis!|t looksjust likeany other class, with aclassand an instancevariable, 
aconstructor, and two normal method implementations. T hen there are four native method 
declarations. You'll recognize these, from previous discussions, as being just anormal method 
declaration with the code block replaced by asemicolon and the modifier native added. T hese 
are the methods you have to implement in C code later. 


Finally, there isa somewhat mysterious code fragment at the very end of the class. You should 
recognizethe general construct hereas astatic initializer. Any codebetween the brackets, and 
} is executed exactly once, when the class is first loaded into the system. You take advantage of 
that fact to run something you want to run only once— the loading of the native code library 
you'll create later today. T his ties together the loading of the class itself with the loading of its 
nativecode. If either fails for somereason, the other fails as well, guaranteeing that no “half-set- 
up” version of the class can ever be created. 


Generating Header and Stub Files 


In order to get your hands on Java objects and data types, and to be able to manipulate then 
in your C code, you need to include some special .h files. M ost of these will be located in your 
release directory under the subdirectory called include. (In particular, look at nativeh in that 
directory, and all the headers it points to, if you’re a glutton for detail punishment.) 
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Some of the special forms you need must betailored to fit your class's methods precisely. T hat’s 
where the javah tool comesin. 


Using javah 

T o gneratetheheadersyou need for your native methods, first compilesimp1eFile with javac, 
just as you normally would. T his produces a file named Simple ile.class. T his file must be fed 
to the javah tool, which then generates the header file you need (SimpleFile.h). 


Tip: If the class handed to javan is inside a package, it prepends the package name 
to the header file name (and to the structure names it generates inside that file), 
after replacing all the dots (.) with underscores (_ ) in the package's full name. 
Thus, if simp1eFile is contained in a hypothetical package called 
acme.widgets.files, javah generates a header file named 
acme_widgets files SimpleFileh, and the various names within are renamed in a 
similar manner. 


When running javah, you should pass it only the class name itself, and not the 
filename, which has .class on the end. 


The Header File 
H eve's the output Of javah SimpleFile: 


/* DO NOT EDIT THIS FILE - it is machine generated */ 
#include <native.h> 
/* Header for class SimpleFile */ 


#ifndef _Included_SimpleFile 
#define _Included_SimpleFile 
struct Hjava_lang String; 


typedef struct ClassSimpleFile { 
#define SimpleFile_separatorChar 62L 
struct Hjava_lang String *path; 

long fd; 

} ClassSimpleFile; 
HandleTo(SimpleFile) ; 


extern /*boolean*/ long SimpleFile_open(struct HSimpleFile *); 

extern void SimpleFile_close(struct HSimpleFile *); 

extern long SimpleFile_read(struct HSimpleFile *,HArrayOfByte *,long); 

extern long SimpleFile_write(struct HSimpleFile *,HArrayOfByte *,long); #endif 
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Note: HandieTo() iS a “magic” macro that uses the structures created at run-time by 
the stubs you'll generate later today. 


The members of the struct generated above are in a one-to-one correspondence with the 
variables of your class. 


In order to “massage” an instance of your class gently into theland of C, usethemacro unhand() 
(asin “unhand that O bject!”). For example, thethis pseudo-variablein J avaappearsasa struct 
HSimpleFile * in theland of C, and to use any variables inside this instance (you), you must 
unhand() yourself first. You'll see some examples of this in a later section today. 


Using javah -stubs 


To “run interference” between the] ava world of O bjects, arrays, and other high-level constructs 
and the lower-level world of C, you need stubs. 


NEWee _Stubsare pieces of “glue” code that automatically translate arguments and return values 
TERM_ back and forth between the worlds of Java and C. 


Stubs can be automatically generated by javah, just likethe headers. T hereisn’t much you need 
to know about thestubsfile, just that it hasto be compiled and linked with theC code you write 
to allow it to interface with J avaproperly. A stubsfile(SimpleFile.c) iscreated by running javah 
on your class by using the option -stubs. 


Note: O ne interesting side-effect of stub generation is the creation of method 
ggnatures, informally called method descriptions elsewhere. T hese signatures are 
quite useful— they can be passed to special C functions that allow you to call back 
into the} ava world from C. You can use stub generation to learn what these 
signatures look like for different method arguments and return values, and then use 
that knowledge to call arbitrary Java methods from within your C code. (Brief 
descriptions of these special C functions, along with further details, appear later 
today.) 


The Stubs File 
H ere’s the result of running javah -stubs SimpleFile: 


/* DO NOT EDIT THIS FILE - it is machine generated */ 
#include <StubPreamble.h> 
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/* Stubs for class SimpleFile */ 

/* SYMBOL: "SimpleFile/open()Z", Java_SimpleFile open_stub */ 

stack_item *Java_SimpleFile_open_stub(stack_item * P_,struct execenv * EE _) { 
extern long SimpleFile_open(void *); 
_P_[0].i = SimpleFile_open(_P_[@].p); 

return _P_ + 1; 


} 

/* SYMBOL: "SimpleFile/close()V", Java_SimpleFile close stub */ 

stack_item *Java_SimpleFile_close_stub(stack_item *_P_,struct execenv *_EE_) { 
extern void SimpleFile_close(void *); 
(void) SimpleFile_close(_P_[0].p); 
return _P_; 


= | 


} 

/* SYMBOL: "SimpleFile/read([BI)I", Java_SimpleFile_read_stub */ 

stack_item *Java_SimpleFile_read_stub(stack_item * P_,struct execenv * EE _) { 
extern long SimpleFile_read(void *,void *,1long) ; 
_P_[0].i = SimpleFile_read(_P_[0].p,((_P_[1].p)),((_P_[2].i))); 
return _P_ + 1; 


} 
/* SYMBOL: "SimpleFile/write([BI)I", Java_SimpleFile_write_stub */ 
stack_item *Java_SimpleFile_write_stub(stack_item *_P_,struct execenv *_EE_) { 
extern long SimpleFile_write(void *,void *,long); 
_P_[0].i = SimpleFile_write(_P_[@].p,((_P_[1].p)),((_P_[2].i))); 
return P_ + 1; 
} 
Each comment line contains the method signature for one of the four native methods you're 
implementing. You can use one of these signatures to call into Java and run, for example, a 
subclass’s overriding implementation of one of your native methods. M ore often, you'd learn 
and useasignatureto call someuseful J ava method from within C to get something donein the 
Java world. 


You do this by calling a special C function in the Java run-time called 
execute_java_dynamic_method().|tsargumentsincludethetarget object of themethod call and 
the method's signature. T he general form of afully qualified method signature is any/package/ 
name /ClassName/methodName(...)X. (YOu Can seeseveral in thelast example, wheresimpleFile 
isthe class name and there is no package name.) T hex isa letter (or string) that represents the 
return type, and the... contains a string that represents each of the argument’s typesin turn. 
H erearethe letters (and strings) used, and the types they represent, in the example [7 is array 
of typeT, BiS byte, 1 iS int, viS void, and Z IS boolean. 


The method c1ose(), which takes no arguments and returns voia, is represented by the string 
"SimpleFile/close()v" and itsinverse, open(), that returns aboolean instead, is represented by 
“SimpleFile/open()z.” Finally, read(), which takes an array of byteS and an int as its two 
arguments and returns an int, iS “SimpleFile/read([B1)1.” (See the “M ethod Signatures” 
section in tomorrow’s lesson for the full details.) 
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Creating SimpleF tleN ative.c 


N ow you can, at last, writetheC code for your Java native methods. 


The header file generated by javah, SimpleFile.h, gives you the prototypes of the four C 
functions you need to implement to make your native code complete. You then writesomeC 
code that provides the native facilities that your | avaclass needs (in this case, somelow-leve file 
1/O routines). Finally, you assembleall theC codeinto anew file includea bunch of required 
(or useful) .h files, and name it SimpleFileN ative.c. H ere’s the result: 


#include "SimpleFile.h" /* for unhand(), among other things */ 
#include <sys/param.h> /* for MAXPATHLEN */ 

#include <fcntl.h> /* for O_RDWR and O_CREAT */ 

#define LOCAL_PATH_SEPARATOR '/' /* UNIX */ 


static void fixSeparators(char *p) { 
for (; *p != '\O'; ++p) 
if (*p == SimpleFile_separatorChar) 
*p = LOCAL_PATH_SEPARATOR; 
} 


long SimpleFile_open(struct HSimpleFile *this) { 
int fd; 
char buffer[MAXPATHLEN] ; 


javaString2CString(unhand(this) ->path, buffer, sizeof (buffer) ); 
fixSeparators(buffer) ; 
if ((fd = open(buffer, O_RDWR |; O CREAT, 0664)) < @) /* UNIX open */ 
return(FALSE); /* or, SignalError() could throw an exception */ 
unhand(this) ->fd = fd; /* save fd in the Java world */ 
return(TRUE) ; 
} 


void SimpleFile_close(struct HSimpleFile *this) { 
close(unhand(this) ->fd) ; 
unhand(this) ->fd = -1; 

} 


long SimpleFile_read(struct HSimpleFile *this, HArrayOfByte *buffer, 

= long count) { 
unhand(buffer)->body; /* get array data *] 
obj_length(buffer) ; /* get array length */ 
(len < count ? len : count); 


char *data 
int len 
int numBytes 


if ((numBytes = read(unhand(this)->fd, data, numBytes)) == 0) 
return(-1); 
return(numBytes) ; /* the number of bytes actually read */ 


] 


long SimpleFile_write(struct HSimpleFile *this, HArrayOfByte *buffer, 
long count) { 


char *data = unhand(buffer) ->body; 
int len = obj_length(buffer) ; 


return(write(unhand(this)->fd, data, (len < count ? len : count))); 
} 
Once you finish writing your .c file, compile it by using your local C compiler (usually called 
cc OF gcc). On somesystems, you may need to specify special compilation flagsthat mean “make 
it relocatable and dynamically linkable.” 


Note: If you don’t haveaC compiler on your computer, you can always buy one. 
You also could get a copy of the GNU C compiler (gcc), one of the best C compil- 
ers in the world, which runs on almost every machine and operating system on the 
planet. T he best way to get gcc isto buy the “GNU release” on CD-ROM, the 
profits of which go to support the Free Software Foundation. You can find both 
theGNU CD-ROM and theLinux CD-ROM (which includes GN U) in select 
places that sell software or technical books, or you can contact the F.S.F. directly. 
TheGNU CD-ROM isa bit pricey, and, though the Linux CD-ROM is very 
inexpensive, if you can’t afford either, or want the latest version and already own a 
CD-ROM, you can download the gzip file ftp: //prep.ai.mit.edu/pub/gnu/gcc- 
2.7.0.tar.gz, which contains all 7M of the latest gcc release. (If you'd like to make 
a donation to, or buy gece or its manual from, the F.S.F., you can email them at 
gnu@prep.ai.mit.edu Or Call 617.542.5942.) 


Some Useful Functions 

When writing theC code for native implementations, a whole set of useful (internal) macros 
and functions areavailablefor accessing J avarun-timestructures. (Several of them were used in 
SimpleFileN ative.c.) 


Let's take a brief digression to understand some of them alittle better. 


functions. Because they’re all internal to the J ava run-time, they're subject to change 
at any moment. Check to see what the latest versions of then look likein your J ava 
release before using them. 


a Warning: D on't rely on the exact form given for any of the following macros and 
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Note: T he following brief descriptions are taken from an alpha release of J ava, 
because descriptions of then for the beta release were not available as of this 
writing. H ow Java data types map into C types, and vice versa, is detailed in the 
documentation there Refer to it for more details on that or on any of the sparsely 
documented items below. (M any are listed just to give you a taste of the capabilities 
of the available functions.) 


The following example: 


Object *unhand(Handle *) 
int obj_length(HArray *) 


returns a pointer to the data portion of an object and returns thelength of an array. T he actual 
pointer type returned is not always object *, but varies, depending on the type of Handle (or 
HArray). 

This example: 


ClassClass *FindClass(struct execenv *e, char *name, bool_t resolve) 
HArrayOfChar *MakeString(char *string, long length) 
Handle *ArrayAlloc(int type, int length) 


finds a class (given itsname), makesan array of characters of length length and allocates an array 
of the given 1ength and type. 
Use the function: 


long execute_java_dynamic_method(ExecEnv *e, HObject *obj, char *method_name, 
char *signature, ...); 


to call aJavamethod from C. eisnuct to usethecurrent environment. T hetarget of themethod 
call is obj. Themethod method_name has the given method signature. It can have any number 
of arguments and returns a 32-bit value (int, Handle *, or any 32-bit C type). 


Use the following: 


HObject *execute_java_constructor(ExecEnv *e, char *classname, ClassClass *c, 
char *signature, ...); 


long execute_java_static_method(ExecEnv *e, ClassClass *c, char *method_name, 
char *signature, ...); 


to call aJ ava constructor from C and call aclassmethod from C. c isthe target class; the rest are 
aS in executemethod(). 


Calling this: 


SignalError(®, JAVAPKG "ExceptionClassName", "message"); 


posts aJ ava exception that will bethrown when your native method returns. It issomewhat like 
the] ava code: 


throw new ExceptionClassName("message") ; 


Finally, here are some useful string conversion functions: 


void javaStringPrint(Hjava_lang String *s) 
int javaStringLength(Hjava_lang_ String *s) 


Hjava_lang String *makeJavaString(char *string, int length) 


char *makeCString(Hjava_lang String *s) 
char *allocCString(Hjava_lang String *s) 


unicode *javaString2unicode(Hjava_lang String *s, unicode *buf, int len) 

char *javaString2CString(Hjava_lang String *s, char *buf, int len) 

The first two methods print a Java string (like system.out.print()), and get its length, 
respectively. T hethird makesa] avastring out of aC string. T hefourth and fifth do thereverse, 
turning a] ava string into aC string (allocated from temporary or heap storage, respectively). 
Thefinal two methods copy J ava strings into preexisting Unicode or ASCII C buffers. 


Compiling the Stubs File 


Thefinal step you need to takein theC world isto compile the stubs file SimpleFile.c by using 
the same compilation flags you used for SimpleFileN ative.c. 


Note: |f you have several classes with native methods, you can include all their 
stubsin the same.c file, if you like Of course you might want to name it some 
thing else, such as Stubs.c, in that case. 


You're now finished with all the C code that must be written (and compiled) to make your 
loadable native library. 


A Native Library 


N ow you'll finally be able to tie everything together and create the native library, simple, that 
was assumed to exist at the beginning of today’s lesson. 


417 


®@ DAY @ 
Native Methods and Libraries 


Linking It All 


It’s time to link everything you've done into asingle library file T his looks alittle different on 
each system that J ava runs on, but here's the basic idea, in UNIX syntax: 


cc -G SimpleFile.o SimpleFileNative.o -o simple 


The -a flag tells the linker that you're creating a dynamically linkable library; the details differ 
from system to system. 


Note: By naming the library simpie, you're disobeying a UNIX convention that 
dynamic library names should have the prefix lib and the suffix .so (on your system, 
these prefixes and suffixes may differ). You can call your library libsimple.so to 
obey the convention, if you like, but just for the clarity of this example, the simpler 
name is used. 


Using Your Library 


N ow, when the] avaclasssimpleFile isfirst loaded into your program, thesystemclassattempts 
to load the library named simple, which (luckily) you just created. Look back at the] ava code 
for simpleFile to renind yourself. 


H ow doesit locateit?!t callsthedynamic linker, which consultsan environment variablenamed 
LD_LIBRARY_PATH that tellsit which sequenceof directoriesto search when loading new libraries 
of native code. Because the current directory isin Java's load path by default, you can leave 
“simple” in the current directory, and it will work just fine. 


Summary 


Today, you learned about the numerous disadvantages of using native methods, about the 
many ways that J ava (and you) can make your programs run faster, and also about the often 
illusory need for efficiency. 


Finally, you learned the procedure for creating native methods, from both the] ava and theC 
sides, in detail— by generating header files and stubs, and by compiling and linking a full 
example. 


After working your way through today’s difficult material, you've mastered one of the most 
complex parts of the] ava language. You now know how theJava run-time environment itself 
was created, and how to extend that powerful environment yourself, at its lowest levels. 
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Asareward, tomorrow you look “under thehood” to seesomeof thehidden power of J ava, and 
you can just sit back and enjoy the ride 


Q&A 


Q 


A 


po) 


W hat can I use to supplement the “Implementing Native M ethods” document 
you recommended? 


Looking online is highly recommended. N earby and within “Implementing N ative 
M ethods’” isa M akefile, other related build information, and amore detailed version 
of both the next example in this book and its explanation. T his following discussion 
will be enough to get you started on your first native methods. 


D oes the J ava class library need to call System.loadL ibrary() to load the built-in 
classes? 


No, you won't see any loadLibrary() callsin theimplementation of any classesin the 
Java class library. T hat’s because the J ava team had the luxury of being able to stati- 
cally link most of their code into the J ava environment, something that really makes 
sense only when you're in the unique position of providing an entire system, as they 
are. Your classes must dynamically link their libraries into an already-running copy of 
the ava system. T hisis, by the way, more flexible than static linking; it allows you to 
unlink old and relink new versions of your classes at any time, making updating then 
trivial. 


Can | statically link my own classes into J ava like the J ava team did? 


Yes. You can, if you like, ask Sun Microsystems for the sources to the J ava run-time 
environment itself, and, as long as you obey the (relatively straightforward) legal 
restrictions on using that code, you can relink the entire J ava system plus your classes. 
Your classes are then statically linked into the system, but you have to give everyone 
who wants to use your program this special version of the ava environment. Some. 
times, if you have strong enough requirements, this is the only way to go, but most of 
the time, dynamic linking is not only good enough, but preferable. 


My applet needs some key functionality, missing from the) ava library. Given 
their many disadvantages, I’d like to avoid using native methods. Dol have any 
alternatives? 


Because it’s still early in the history of J ava, a valid alternative to native methods is to 
try to convince the ava team that your needed capability is of interest to a broad 
range of future J ava programmers; then they may include it directly into the java 
packages. T here are already plans to do this with certain “missing” pieces of function- 
ality, so this may not be as hard asell as you might think. Start by posting some 
messages to the comp. 1ang. java Newsgroup, to be sureno one ese at Sun or elsewhere 
is already doing it, and then see what happens. T hisis a young, vibrant community of 
enthusiasts; you are not alone. 
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On today, your final day, the inner workings of the J ava system will be revealed. 


You'll find out all about J ava’s vision, J ava’s virtual machine, those bytecodes you’ve heard so 
much about, that mysterious garbage collector, and why you might worry about security but 
don’t have to. 


Let’s begin, however, with the big picture. 


The Big Picture 


T he} avateam isvery ambitious. T heir ultimate goal isnothinglessthan to revolutionizetheway 
softwareis written and distributed. T hey've started with the! nternet, where they believe much 
of the interesting software of the future will live. 


To achieve such an ambitious goal, alarge fraction of the Internet programming community 
itself must be marshalled behind a similar goal and given the tools to help achieveit. T he] ava 
language, with its four S’s (small, simple, safe, secure), and its flexible net-oriented environ- 
ment, hopes to become the focal point for the rallying of this new legion of programmers. 


To this end, Sun Microsystems has done something rather gutsy. W hat was originally a secret, 
tens-of-millions-of-dollars research and development project, and 100 percent proprietary, has 
becomeafree, open, and relatively unencumbered technology standard upon which anyonecan 
build. T hey are literally g ving it away and reserving only the rights they need to maintain and 
grow the standard. 


Note: Actually, as Sun’s lawyers have more and more time to think, the original 
intentions of the] ava team get further obscured by legal details. It is still relatively 
unencumbered, but its earlier releases were completely unencumbered. Let’s hope 
that this is not a pattern that will continue. 


Any truly open standard must be supported by at least one excellent, freely available “denon- 
stration” implementation. Sun has already shipped an alpha, and now a beta, of one to the 
Internet and plans on a final release soon. In parallel, several universities, companies, and 
individuals have already expressed their intention to duplicate the] ava environment, based on 
the open API that Sun has created. 


Several other languages are even contemplating compiling down to Java bytecodes, to halp 
support then in becoming a more robust and commonplace standard for moving executable 
content around on theN et. 
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Why It’s a Powerful Vision 


O neof the reasons this brilliant move on Sun’s part has a real chance of success is the pent-up 
frustration of literally a whole generation of programmers who desperately want to share their 
code with one another. Right now, the computer science world is balkanized into factions at 
universities and companies all over the world, with hundreds of languages, dozens of them 
widely used, dividing and separating usall. It’sthe worst sort of T ower of Babel. J ava hopes to 
build some bridges and help tear down that tower. Becauseit isso simple, because it’s so useful 
for programming over the Internet, and because the Internet is so “hot” right now— this 
confluence of forces should help propel J ava onto centerstage. 


It deserves to bethere It isthenatural outgrowth of ideas that, sincethe early 1970sinsidethe 
Smalltalk group at Xerox PARC, havelain relatively dormant in the mainstream. Smalltalk, in 
fact, invented the first object-oriented bytecode interpreter and pioneered many of the deep 
ideas that J ava builds on today. T hose efforts were not embraced over the intervening decades 
as a solution to the general problems of software, however. Today, with those problems 
becoming so much moreobvious, and with theN et crying out for anew kind of programming, 
the soil is fertile to grow something stronger from those old roots, something that just might 
spread like wildfire. (Is it a coincidence that J ava’s previous internal names were Green and 
OAK?) 


This new vision of software is onein which the N et becomes an ocean of objects, classes, and 
the open APIs between them. Traditional applications have vanished, replaced by skeletal 
frameworkslikethe Eiffel tower, into which can befitted any partsfrom thisocean, on demand, 
to suit any purpose. U ser interfaces will be mixed and matched, built in pieces and constructed 
to taste, whenever the need arises, by thar own users M enusof choiceswill befilled by dynamic 
lists of all the choices available for that function, at that exact moment, across the entire ocean 
(of the N et). 


In such aworld, software distribution isno longer an issue. Software will beeveywhereand will 
be paid for viaa plethora of new micro-accounting models, which charge tiny fractions of cents 
for the parts as they are assembled and used. Frameworks will come into existence to support 
entertainment, business, and the social (cyber-)spaces of the near future. 


Thisisadream that many of us have waited all our livesto bea part of. T here are trenendous 
challenges to making it all cometrue, but the powerful winds of change weall feel must stir us 
into action, because, at last, there is a base on which to build that dream— J ava. 


The J ava Virtual Machine 


To make visions like this possible, Java must be ubiquitous. It must be able to run on any 
computer and any operating system— now, and in the future In order to achieve this level of 
portability, Java must be very precise not only about the language itself, but about the 
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environment in which the language lives. You can see, from earlier in the book and Appendix 
B, that the J ava environment includes a generally useful set of packages of classes and a freely 
available implementation of them. T his takes care of a part of what is needed, but it is crucial 
also to specify exactly how the run-time environment of J ava behaves. 


This final requirenent is what has stymied many attempts at ubiquity in the past. If you base 
your system on any assumptions about what is “beneath” the run-time system, you lose. If you 
depend in any way on thecomputer or operating system below, you lose. J avasolvesthisproblem 
by inventing an abstract computer of its own and running on that. 


This “virtual” machine runs a special set of “instructions” called bytecodes that are simply a 
stream of formatted bytes, each of which hasaprecisespecification of exactly what each bytecode 
does to this virtual machine. The virtual machine is also responsible for certain fundamental 
capabilities of Java, such as object creation and garbage collection. 


Finally, in order to be able to move bytecodes safely across the Internet, you need a bulletproof 
model of security— and how to maintain it— and a precise format for how this stream of 
bytecodes can be sent from one virtual machine to another. 


Each of these requirements is addressed in today’s lesson. 


Note: T his discussion blurs the distinction between the run-time and the virtual 
machine of J ava. This is intentional but a little unconventional. Think of the 
virtual machine as providing all the capabilities, even those that are conventionally 
assigned to the run-time. T his book uses the words “run-time” and “virtual 
machine” interchangeably. Equating the two highlights the single environment that 
must be created to support Java. 


M uch of the following description is based closely on the alpha “Virtual M achine 
Specifications” documents (and the beta bytecodes), so if you delve more deeply 
into the details online, you will cover some familiar ground. 


An Overview 


It isworth quoting the introduction to the] ava virtual machine documentation here, because 
it isso relevant to the vision outlined earlier: 


T he] ava virtual machine specification has a purpose that is both like and unlike 
equivalent documents for other languages and abstract machines. It is intended to 
present an abstract, logical machine design free from the distraction of inconsequential 
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details of any implementation. It does not anticipate an implementation technology, 
or an implementation host. At the same time it gives a reader sufficient information to 
allow implementation of the abstract design in a range of technologies. 


H owevey, the intent of the [...] J ava project is to create a language [...] that will allow 
the interchange over the Internet of “executable content,” which will be embodied by 
compiled J ava code. T he project specifically does not want J ava to be a proprietary 
language and does not want to be the sole purveyor of J ava language implementations. 
Rather, we hope to make documents like this one, and source code for our implemen- 
tation, freely available for people to use as they choose. 


This vision [...] can be achieved only if the executable content can be reliably shared 
between different J ava implementations. T hese intentions prohibit the definition of 
the J ava virtual machine from being fully abstract. Rather, relevant logical elements of 
the design have to be made sufficiently concrete to allow the interchange of compiled 
Java code. T his does not collapse the J ava virtual machine specification to a descrip- 
tion of aJ ava implementation; elenents of the design that do not play a part in the 
interchange of executable content remain abstract. But it does force us to specify, in 
addition to the abstract machine design, a concrete interchange format for compiled 
Java code. 


TheJava virtual machine specification consists of the following: 


The bytecode syntax, including opcode and operand sizes, values, and types, and their 
alignment and endian-ness 


The values of any identifiers (for example, type identifiers) in bytecodes or in support- 
ing structures 


T he layout of the supporting structures that appear in compiled J ava code (for 
example, the constant pool) 


[] TheJava .class file format 


Each of these is covered today. 


Despite this degree of specificity, there are still several dements of the design that remain 
(purposely) abstract, including the following: 

_] Thelayout and management of the run-time data areas 

_] The particular garbage-collection algorithms, strategies, and constraints used 


_] Thecompiler, development environment, and run-time extensions (apart from the 
need to generate and read valid J ava bytecodes) 


Any optimizations performed, once valid bytecodes are received 


T hese places are where the creativity of a virtual machine implenentor has full rein. 
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The Fundamental Parts 


T he] ava virtual machine can be deconstructed into five fundamental pieces: 


"| A bytecode instruction set 
A set of registers 

A stack 

A garbage-collected heap 
An area for storing methods 


T hese might be implemented by using an interpreter, a native binary code compiler, or even a 
hardware chip— but all these logical, abstract components of the virtual machine must be 


supplied in some form in every J ava system. 


Note: T he memory areas used by theJ ava virtual machine are not required to be at 
any particular placein memory, to bein any particular order, or even to use 
contiguous memory. H owever, all but the method area must be able to represent 
32-bit values (for example, the Java stack is 32 bits wide). 


Thevirtual machine, and its supporting code, isoften referred to astherun-time environment, 
and when this book refers to something being doneat run-time, the virtual machine is what's 
doing it. 


J ava B ytecodes 

T he} ava virtual machine instruction set isoptimized to besmall and compact. It isdesigned to 
travel across the N et, and so has traded off speed-of-interpretation for space. (Given that both 
N et bandwidth and mass storage speeds increase less rapidly than CPU speed, this seems like 
an appropriate trade-off.) 


Asmentioned, J avasourcecodeis“compiled” into bytecodesand stored in a.classfile. On Sun’s 
Java system, this is performed using the javac tool. It is not exactly a traditional “compiler,” 
because javac translates source code into bytecodes, a lower-level format that cannot be run 
directly, but must be further interpreted by each computer. Of course, it is exactly this level of 
“indirection” that buys you the power, flexibility, and extreme portability of J ava code. 
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Note: Q uotation marks are used around the word “compiler” when talking about 
javac because later today you will also learn about the “just-in-time” compiler, 
which acts more like the back end of a traditional compiler. T he use of the same 
word “compiler” for these two different pieces of J ava technology is unfortunate, 
but somewhat reasonable, because each is really one-half (either the front or the 
back end) of amore traditional compiler. 


A bytecode instruction consists of a one-byte opcode that serves to identify the instruction 
involved and zero or moreoperands, each of which may bemorethan onebytelong, that encode 
the parameters the opcode requires. 


Note: W hen operands are more than one byte long, they are stored in big-endian 
order, high-order byte first. T hese operands must be assembled from the byte 
stream at run-time. For example, a 16-bit parameter appears in the stream as two 
bytes so that its value is first_byte * 256 + second _byte. | he bytecode instruc- 
tion stream is only byte-aligned, and alignment of any larger quantities is not 
guaranteed (except for “within” the special bytecodes 1ookupswitch and 
tableswitch, which have special alignment rules of their own). 


Bytecodesinterpret datain therun-time’s memory areas as belonging to a fixed set of types: the 
primitive types you've seen several times before, consisting of several signed integer types (8-bit 
byte, 16-bit short, 32-bit int, 64-bit 1ong), one unsigned integer type (16-bit char), and two 
signed floating-point types (32-bit tioat, 64-bit doub1e), plus the type “reference to an object” 
(a 32-bit pointer-like type). Some special bytecodes (for example, the dup instructions), treat 
run-time memory areas as raw data, without regard to type T hisisthe exception, however, not 
the rule. 


T hese primitive types are distinguished and managed by the compiler, javac, not by the] ava 
run-time environment. T hese types are not “tagged” in memory, and thus cannot be distin- 
guished at run-time. Different bytecodes are designed to handle each of the various primitive 
types uniquely, and the compiler carefully chooses from this palette based on its knowledge of 
the actual types stored in the various memory areas. F or example, when adding two integers, the 
compiler generates an iaad bytecode; for adding two floats, faad is generated. (You'll seeall this 
in gruesome detail later.) 
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Registers 


The registers of the J ava virtual machine are just like the registers inside a “real” computer. 


NEWee Registers hold the machine's state, affect its operation, and are updated after each 
TERM bytecode is executed. 


The following are the J ava registers: 


pe, the program counter, which indicates what bytecode is being executed 

optop, a pointer to the top of the operand stack, which is used to evaluate all arith- 
metic expressions 

_] frame, apointer to the execution environment of the current method, which includes 
an activation record for this method call and any associated debugging information 


(J vars, apointer to the first local variable of the currently executing method 
The virtual machine defines these registers to be 32 bits wide. 


Note: Because the virtual machine is primarily stack-based, it does not use any 
registers for passing or receiving arguments. T his is a conscious choice skewed 
toward bytecode simplicity and compactness. It also aids efficient implementation 
on register-poor architectures, which most of today’s computers, unfortunately, are. 
Perhaps when the majority of CPUs out there area little more sophisticated, this 
choice will be reexamined, though simplicity and compactness may still be reason 
enough! 


By the way, the pe register is also used when the run-time handles exceptions; catch 
clauses are (ultimately) associated with ranges of the pe within a method's 
bytecodes. 


The Stack 


The Java virtual machine is stack-based. A J ava stack frame is similar to the stack frame of a 
conventional programming language— it holds the state for a single method call. Frames for 
nested method calls are stacked on top of this frame. 


NEWee- Thedsack is used to supply parameters to bytecodes and methods, and to 
TERM receive results back from them. 
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Each stack frame contains three (possibly empty) sets of data: the local variables for themethod 
call, its execution environment, and its operand stack. T hesizes of these first two are fixed at the 
start of a method call, but the operand stack varies in size as bytecodes are executed in the 
method. 


Local variables are stored in an array of 32-bit slots, indexed by theregister vars. M ost typestake 
up oneslot in the array, but the 1ong and double types each take up two slots. 


Note: 1ong and double values, stored or referenced viaan index N, take up the (32- 
bit) slotsN andN +1. These 64-bit values are thus not guaranteed to be 64-bit- 
aligned. | mplementors are free to decide the appropriate way to divide these values 
among the two slots. 


The execution environment in a stack frame helps to maintain the stack itself. It contains a 
pointer to the previous stack frame, a pointer to the local variables of the method call, and 
pointers to the stack’s current “base” and “top.” Additional debugging information can also be 
placed into the execution environment. 


The operand stack, a 32-bit first-in-first-out (FIFO ) stack, is used to store the parameters and 
return values of most bytecodeinstructions. For example, theiada bytecodeexpectstwo integers 
to be stored on thetop of thestack. It popsthem, addsthem together, and pushes theresulting 
sum back onto the stack. 


Each primitive data type has unique instructions that know how to extract, operate, and push 
back operands of that type. For example, 1ong and double operandstaketwo “slots” on thestack, 
and the special bytecodes that handle these operands take this into account. It is illegal for the 
types on the stack and the instruction operating on them to be incompatible (javac outputs 
bytecodes that always obey this rule). 


Note: T he top of the operand stack and the top of the overall J ava stack are almost 
always the same. T hus, “the stack,” refers to both stacks, collectively. 


The Heap 
The heap is that part of memory from which newly created instances (objects) are allocated. 
In Java, the heap is often assigned a large, fixed size when theJ ava run-time system is started, 


but on systems that support virtual memory, it can grow as needed, in a nearly unbounded 
fashion. 
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Because objects are automatically garbage-collected in Java, programmers do not have to 
(and, in fact, cannot) manually free the memory allocated to an object when they are finished 
using it. 


J ava objects are referenced indirectly in the run-time, via handles which area kind of pointer 
into the heap. 


Because objects are never referenced directly, parallel garbage collectors can be written that 
operateindependently of your program, moving around objectsin theheap at will. You'll learn 
more about garbage collection later. 


The Method Area 


Like the compiled code areas of conventional programming language environments, or the 
TEXT segment in aU NIX process, the method area stores the] ava bytecodes that implement 
almost every method in the] ava system. (Remember that some methods might be native, and 
thus implemented, for example, in C.) The method area also stores the symbol tables needed 
for dynamic linking, and any other additional information debuggers or development environ- 
ments which might want to associate with each method’s implementation. 


Because bytecodes are stored as byte streams, the method area is aligned on byte boundaries. 
(T he other areas are all aligned on 32-bit word boundaries.) 


The Constant Pool 


In the heap, each class has a constant pool “attached” to it. U sually created by javac, these 
constants encode all the names (of variables, methods, and so forth) used by any method in a 
class. T heclasscontainsacount of how many constantsthereareand an offset that specifieshow 
far into the class description itself the array of constants begins. T hese constants are typed by 
using specially coded bytes and havea precisely defined format when they appear in the .class 
filefor a class. Later today, alittle of this file format is covered, but everything is fully specified 
by the virtual machine specifications in your J ava release. 


Limitations 


The virtual machine, as currently defined, places some restrictions on legal Java programs by 
virtue of thechoicesit hasmade(somewere previously described, and morewill bedetailed later 
today). 


T hese limitations and their implications are 


(| 32-bit pointers, which imply that the virtual machine can address only 4G of memory 
(this may be relaxed in later releases) 
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Unsigned 16-bit indicies into the exception, line number, and local variable tables, 
which limit the size of a method's bytecode implementation to 64K (this limitation 
may be eliminated in the final release) 


Unsigned 16-bit indices into the constant pool, which limits the number of constants 
in aclass to 64K (a limit on the complexity of a class) 


In addition, Sun’simplenentation of thevirtual machineusesso-called_quick bytecodes, which 
further limit the system. U nsigned 8-bit offsets into objects may limit the number of methods 
in aclassto 256 (thislimit may not exist in thefinal release), and unsigned 8-bit argument counts 
limit the size of the argument list to 255 32-bit words. (Although this means that you can have 
up to 255 arguments of most types, you can haveonly 127 of them if they’reall 1ong Or doub1e.) 


B ytecodes in More Detail 


O neof themain tasks of the virtual machineisthe fast, efficient execution of the] ava bytecodes 
in methods. U nlikein the discussion yesterday about generality in Java programs, thisis a case 
where speed is of the upmost importance. Every J ava program suffers from a slow implemen- 
tation here, so the run-time must use as many “tricks” as possible to make bytecodes run fast. 
T heonly other goal (or limitation) isthat J ava programmers must not be ableto see these tricks 
in the behavior of their programs. 


A Javarun-time implenenter must be extremely clever to satisfy both these goals. 


T he B ytecode I nter preter 


A bytecode interpreter examines each opcode byte (bytecode) in a method’s bytecode stream, 
in turn, and executes a unique action for that bytecode. T his might consume further bytes for 
theoperandsof thebytecodeand might affect which bytecodewill be examined next. It operates 
likethehardwareC PU in acomputey, which examinesmemory for instructionsto carry out in 
exactly the same manner. It isthe software CPU of theJava virtual machine. 


Your first, naiveattenpt to writesuch abytecodeinterpreter will almost certainly bedisastrously 
slow. Theinner loop, which dispatches one bytecodeeach timethrough theloop, isnotoriously 
difficult to optimize. In fact, smart people have been thinking about this problem, in one form 
or another, for more than 20 years. Luckily, they've gotten results, all of which can be applied 
to J ava. 


T hefinal result isthat theinterpreter shipped in the current release of J avahas an extremely fast 
inner loop. In fact, on even arelatively slow computer, this interpreter can perform more than 
330,000 bytecodes per second! T hisisreally quitegood, becausetheC PU in that computer does 
only about 30 times better using hardware. 
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Thisinterpreter is fast enough for most J avaprograms (and for thoserequiringmore speed, they 
can always use native methods— see yesterday's discussion)— but what if asmart implenentor 
wants to do better? 


T he “J ust-in-Time” Compiler 


About a decade ago, a really clever trick was discovered by Peter D eutsch while trying to make 
Smalltalk run faster. H ecalled it “dynamic translation” during interpretation. Sun callsit “just- 
in-time” compiling. 


Thetrick is to notice that the really fast interpreter you've just written— in C, for example— 
already hasa useful sequence of native binary codefor each bytecode that it interprets: thebinary 
codethat theinterpreter itself isexecuting. Becausetheinterpreter has already been compiled from 
C into native binary code, for each bytecode that it interprets, it passes through a sequence of 
native codeinstructions for thehardwareC PU on which it isrunning. By saving a copy of each 
binary instruction as it “goes by,” the interpreter can keep arunning log of the binary code it 
itsaf has run to interpret a bytecode. It can just as easily keep a log of the set of bytecodes 
that it ran to interpret an entire method. 


You takethat log of instructionsand “peephole-optimize’ it, just asa smart compiler does. T his 
eliminates redundant or unnecessary instructions from the log, and makes it look just likethe 
optimized binary code that a good compiler might have produced. 


Note: T his is where the name compiler comes from, in “just-in-time” compiler, 
but it’s really only the back end of a traditional compiler— the part that does code 
generation. By the way, the front end here is javac. 


H ere’s where the trick comesin. The next time that method is run (in exactly the same way), 
theinterpreter can now simply execute directly thestored log of binary native code. Becausethis 
optimizes out the inner-loop overhead of each bytecode, as well as any other redundancies 
between the bytecodes in a method, it can gain a factor of 10 or more in speed. In fact, an 
experimental version of this technology at Sun has shown that J ava programs using it can run 
as fast as compiled C programs. 
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Note: T he parenthetical in the last paragraph is needed because if anything is 
different about the input to the method, it takes a different path through the 
interpreter and must be rdlogged. (T here are sophisticated versions of this technol- 
ogy that solve this, and othe,, difficulties.) T he cache of native code for a method 
must be invalidated whenever the method has changed, and the interpreter must 
pay a small cost up front each time a method is run for the first time. H owever, 
these small bookkeeping costs are far outweighed by the amazing gains in speed 
possible. 


The java2c Translator 


Another, simpler, trick, which works well whenever you havea good, portable C compiler on 
each system that runs your program, is to translate the bytecodes into C and then compile the 
C into binary native code. If you wait until the first use of amethod or class, and then perform 
thisasan “invisible” optimization, it gainsyou an additional speedup over theapproach outlined 
previously, without the J ava programmer needing to know about it. 


Of course, this does limit you to systenswith aC compiler, but as you learned yesterday, there 
areextremely good, freely availableC compilers. In theory, your] avacodemight beableto travel 
with its own C compiler, or know where to pull one from the N et as needed, for each new 
computer and operating system it faced. (Because this violates some of the rules of normal J ava 
code movement over the N et, though, it should be used sparingly.) 


If you're using J ava, for example, to write a server that lives only on your computer, it might be 
appropriate to use Java for its flexibility in writing and maintaining the server (and for its 
capability of dynamically linking new J ava codeon thefly), and then to run java2c by hand to 
translate the basic server itself entirely into native code You'd link the Java run-time 
environment into that codeso that your server remainsafully capable) avaprogram, but it’snow 
an extremely fast one. 


In fact, an experimental version of the javaz2c translator inside Sun shows that it can reach the 
speed of compiled and optimized C code. Thisis the best that you can hope to do! 


Note: U nfortunately, as of the beta release, there is still no publicly available java2c 
tool, and Sun’s virtual machine does not perform “just-in-time” compilation. Both 
of these have been promised in a later release. 
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T he B ytecodes T hemselves 


Let's look at a (progressively less and less) detailed description of each class of bytecodes. 


For each bytecode, some brief text describes its function, and a textual “picture” of the stack, 
both before and after the bytecode has been executed, is shown. T his text picture will look like 
the following: 


.., value1, value2 => ..., value3 


T his means that the bytecode expects two operands— vaiuei and vaiue2— to beon thetop of 
thestack, popsthem both off thestack, operates on them to producevalue3, and pushes value3 
back onto thetop of the stack. You should read each stack from right to left, with the rightmost 
valuebeingthetop of thestack. The... isread as “therest of thestack below,” which isirrelevant 
to the current bytecode. All operands on the stack are 32-bit wide 


Because most bytecodes take their arguments from the stack and place their results back there, 
the brief text descriptions that follow only say something about the source or destination of 
values if they are not on the stack. For example, the description Load integer from local 
variable. meansthat theinteger isloaded onto thestack, and Integer add. intendsitsintegers 
to be taken from— and the result returned to— the stack. 


Bytecodes that don’t affect control flow simply movethepc onto thenext bytecode that follows 
in sequence. T hose that do affect the pc say so explicitly. Whenever you see byte1, byte2, and 
so forth, it refersto thefirst byte, second byte, and so on, that follow theopcodebyteitself. After 
such a bytecode is executed, the pc automatically advances over these operand bytes to start the 
next bytecode in sequence. 


Note: T he next few sections arein “reference manual style,” presenting each 
bytecode separately in all its (often redundant) detail. Later sections begin to 
collapse and coalesce this verbose style into something shorter, and more readable. 
T he verbose form is shown at first because the online reference manuals will look 
more like it, and because it drives home the point that each bytecode “function” 
comes in many, nearly identical bytecodes, one for each primitive type in J ava. 


Pushing Constants onto the Stack 


bipush vas => ..., Value 


Push one-bytesigned integer. byte1 isinterpreted asasigned 8-bit value. T hisvaiue isexpanded 
to an int and pushed onto the operand stack. 
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sipush wee => ..., Value 


Push two-byte signed integer. byte1 and byte2 are assembled into a signed 16-bit value. This 
value IS expanded to an int and pushed onto the operand stack. 


1dc1 we. => ..., item 


Push item from constant pool. byte1 is used as an unsigned 8-bit index into the constant pool 
of the current class. The item at that index is resolved and pushed onto the stack. 


ldc2 we. => ..., item 


Push item from constant pool. byte1 and byte2 are used to construct an unsigned 16-bit index 
into the constant pool of the current class. T he item at that index is resolved and pushed onto 
the stack. 


ldc2w +s => ..., COnStant-word1, constant -word2 


Push 1ong Or double from constant pool. byte1 and byte2 are used to construct an unsigned 16- 
bit index into the constant pool of the current class. The two-word constant at that index is 
resolved and pushed onto the stack. 


aconst_null wee => 2.4, null 

Push the nui1 object reference onto the stack. 
iconst_m1 wee => aang oT 

Push the int -1 onto the stack. 

iconst_<I> wan (EP aac S15 


Push the int <r> onto the stack. T here are six of these bytecodes, one for each of the integers 
0-5: iconst_0, iconst_1, iconst_2, iconst_3, iconst_4, aNd iconst_5. 


lconst_<L> we. => ..., <L>-word1, <L>-word2 


Push the long <L> onto the stack. T here are two of these bytecodes, one for each of the integers 
0 and 1: 1const_o, and 1const_1. 


fconst_<F> wee => aay <F> 


Push thefloat <F> onto thestack. T herearethreeof these bytecodes, onefor each of theintegers 
0-2: fconst_0, fconst_1, and fconst_2. 


dconst_<D> .e. => ..., <D>-word1, <D>-word2 


Push the double <p> onto thestack. T herearetwo of thesebytecodes, onefor each of theintegers 
0 and 1: dconst_, and dconst_1. 
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Loading Local Variables onto the Stack 


iload +. => ..., value 


Load int from local variable. Local variablebyte1 in thecurrent J avaframemust contain an int. 
The value of that variable is pushed onto the operand stack. 


iload_<I> wae => ..., Value 


Load int from local variable. Local variable<1> in the current J ava frame must contain an int. 
T he value of that variable is pushed onto the operand stack. T hereare four of these bytecodes, 
one for each of the integers 0-3: iload_0, iload_1, iload_2, and iload_3. 


lload ... => ..., value-word1, value-word2 


Load 1ong from local variable. Local variablesbyte1 and byte1 + 1in thecurrent] avaframemust 
together contain along integer. T he values contained in those variables are pushed onto the 
operand stack. 


lload_<L> 1. => ..., value-word1, value-word2 


Load 1ong from local variable. Local variables <L> and <L> + 1 in the current Java frame must 
together contain a long integer. The value contained in those variables is pushed onto the 
operand stack. There are four of these bytecodes, one for each of the integers 0-3: 110ad_a, 
lload_1, lload_2, and 1load_3. 


fload +. => ..., value 


Load float from local variable. Local variable byte1 in the current J ava frame must contain a 
single precision floating-point number. T he value of that variable is pushed onto the operand 
stack. 


fload_<F> wee => ..., Value 


Load float from local variable. Local variable<F>in thecurrent J avaframemust contain asingle 
precision floating-point number. T he value of that variable is pushed onto the operand stack. 
T here are four of these bytecodes, one for each of the integers 0-3: t1oad_0, fload_1, fload_2, 
and fload_3. 


dload 1. => ..., value-word1, value-word2 


Load double from local variable. Local variables byte1 and byte1 + 1in thecurrent J avaframe 
must together contain a double precision floating-point number. T he value contained in those 
variables is pushed onto the operand stack. 


dload_<D> +. => ..., Value-word1, value-word2 


Load double from local variable. Local variables <p> and <p> + 1 in the current J ava frame must 
together contain a double precision floating-point number. The value contained in those 
variablesis pushed onto the operand stack T herearefour of these bytecodes, onefor each of the 
integers 0-3: dload_@, dload1, dload_2, and dload_3. 


aload w+. => ..., Value 


Load object reference from local variable. Local variable byte1 in the current J ava frame must 
contain areturn address or reference to an object or array. T he value of that variable is pushed 
onto the operand stack. 


aload_<A> wee => ..., Value 


Load object reference from local variable. Local variable <a> in the current J ava frame must 
contain areturn address or referenceto an object. T hearray valueof that variableis pushed onto 
the operand stack. T here are four of these bytecodes, one for each of theintegers 0-3: aload_o, 
aload_1, aload_2, and aload_3. 


Storing Stack Values into Local Variables 


istore .»., Value =>... 


Store int into local variable. value Must bean int. Local variablebyte1 in thecurrent] avaframe 
is Set to value. 


istore_<I> ..., Value =>... 


Store int into local variable. value Must bean int. Local variable <1> in the current J ava frame 
is set to value. T here are four of these bytecodes, one for each of the integers 0-3: istore_9, 
istore_1, istore 2, and istore 3. 


lstore ..., Value-word1, value-word2 =>... 


Store long into local variable. value must bea long integer. Local variables byte1 and byte1 + 
1 in the current J ava frame are set to value. 


lstore_<L> ..., Value-word1, value-word2 =>... 


Store 1ong into local variable. value must be along integer. Local variables <L> and <L> + 1in 
the current J ava frame are set to value. T here are four of these bytecodes, one for each of the 
integers 0-3: 1store_0, lstore 1, lstore 2, and lstore_3. 


fstore .++; Value SP eee 


Store float into local variable. vaiue must bea single precision floating-point number. Local 
variables byte1 and byte1 + 1 in the current Java frame are set to value. 
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fstore_<F> -++, Value SP nae 


Store float into local variable. value must bea single precision floating-point number. Local 
variables <F> and <F> + 1 in the current J ava frame are set to value. T here are four of these 
bytecodes, one for each of the integers 0-3: fstore_0, fstore_1, fstore_2, and fstore_3. 


dstore ..., Value-word1, value-word2 => ... 


Store double into local variable. value must beadoubleprecision floating-point number. Local 
variables byte and byte1 + 1 in the current Java frame are set to value. 


dstore_<D> ..., Value-word1, value-word2 =>... 


Store double into local variable. value must beadoubleprecision floating-point number. Local 
variables <p> and <p> + 1 in the current Java frame are set to value. T here are four of these 
bytecodes, one for each of the integers 0-3: dstore_0, dstore_1, dstore_2, and dstore_3. 


astore ..., handle =>... 


Store object reference into local variable. handle must bea return address or a reference to an 
object. Local variable byte1 in the current J ava frame is set to value. 


astore_<A> ..., handle =>... 


Store object reference into local variable. handie must bea return address or a reference to an 
object. Local variable <a> in the current J ava frame is set to value. T here are four of these 
bytecodes, one for each of the integers 0-3: astore_0, astore_1, astore_2, and astore_3. 


iinc -no change- 


Increment local variable by constant. Local variablebyte1 in thecurrent) avaframemust contain 
an int. Its value is incremented by the value byte2, where byte2 Is treated as a signed 8-bit 
quantity. 


Managing Arrays 
newarray ..., Size => result 


Allocate new array. size must bean int. It reoresents thenumber of elements in the new array. 
byte1 isan internal codethat indicatesthe type of array to allocate. Possiblevaluesfor byte1 are 
as follows: T_BOOLEAN (4), T_CHAR (5), T_FLOAT (6), T_DOUBLE (7), T_BYTE (8), T_SHORT (9), T_INT 
(10), and T_LONG (11). 


An attempt is made to allocate a new array of the indicated type, capable of holding size 
elements. T his will be the resuit. If size is less than zero, a NegativeArraySizeException is 
thrown. If thereisnot enough memory to allocatethearray, an outotMemoryError isthrown. All 
elements of the array are initialized to their default values. 


anewarray ..., Size => result 


Allocate new array of objects. size must bean int. It represents thenumber of elementsin the 
new array. byte1 and byte2 are used to construct an index into the constant pool of the current 
class. The item at that index is resolved. T he resulting entry must be a class. 


An attempt is made to allocate a new array of the indicated class type, capable of holding size 
elements. This will be the resuit. If size is less than zero, a NegativeArraySizeException is 
thrown. If thereisnot enough memory to allocatethe array, an outofmemoryError isthrown. All 
elements of the array are initialized to nuit. 


Note: anewarray iS used to create a single dimension of an array of objects. For 
example, the request new Thread[7] generates the following bytecodes: 


bipush 7 
anewarray <Class "java.lang.Thread"> 
anewarray Can also be used to create the outermost dimension of a multidimen- 
sional array. For example, the array declaration new int[6][] generates this: 
bipush 6 


anewarray <Class "[I"> 


(See the section “M ethod Signatures” for more information on strings such as I.) 


multianewarray ..., Size1 size2...sizeN => result 


Allocatenew multidimensional array. Each size<1> must bean int. Each representsthenumber 
of elementsin adimension of thearray. byte1 and byte2 areused to construct an index into the 
constant pool of the current class. T he item at that index is resolved. T he resulting entry must 
bean array class of one or more dimensions. 


bytes iSapositive integer representing thenumber of dimensions being created. It must beless 
than or equal to thenumber of dimensionsof thearray class. bytes is also thenumber of dements 
that are popped off the stack. All must be ints greater than or equal to zero. T hese are used as 
thesizesof thedimensions. An attenptismadeto allocate anew array of theindicated classtype, 
capable of holding size<1> * size<2> * ... * <sizen> ements. Thiswill betheresuit. If any 
of thesize<r>argumentson thestack islessthan zero, aNegativeArraySizeExceptionisthrown. 
If there is not enough memory to allocate the array, an outofmemoryError is thrown. 
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Note: new int[6][3][] generates these bytecodes: 
bipush 6 
bipush 3 
multianewarray <Class "[[[I"> 2 


It’s more efficient to use newarray OF anewarray when creating arrays of single 
dimension. 


arraylength .e+y array => ..., length 


Get length of array. array must be a reference to an array object. The 1ength of the array is 
determined and replaces array On thetop of thestack. If array isnull, aNu11PointerException 
is thrown. 


iaload » array, index => 5» value 
laload » array, index => ,» value-word1, value-word2 
faload » array, index => ; value 
daload +++, array, index => ..., value-word1, value-word2 
aaload .+ey array, index => ..., value 
baload » array, index => ; value 
caload » array, index => ; value 
saload » array, index => ; value 


Load <type> from array. array Must bean array of <type>s. index Must bean int. The<type> 
value at position number index in array is retrieved and pushed onto the top of the stack. If 
array iSnull, ANu1l1PointerException isthrown. If index isnot within the bounds of array, an 
Array IndexOutOfBoundsException iSthrown. <type> is, in turn, int, long, float, double, object 
reference, byte, char, and short. <type>S long and double havetwo word valueS, as you've seen 
in previous 1oad bytecodes. 


iastore array, index, value =>... 
lastore array, index, value-word1, value-word2 => ... 
fastore array, index, value =>... 
dastore array, index, value-word1, value-word2 => ... 


3 
3 
3 
ere 
aastore +++; array, index, value =>... 
3 
] 
] 


bastore array, index, value =>... 
castore array, index, value =>... 
sastore array, index, value =>... 


Storeinto <type> array. array Must bean array of <type>s, index Must bean integer, and value 
a <type>. The <type> value is stored at position index in array. If array iS null, a 
NullPointerException iS thrown. If index is not within the bounds of array, an 
Array IndexOutOfBoundsException iSthrown. <type> is, in turn, int, long, float, double, object 
reference, byte, char, and short. <type>S long and double havetwo word valueS, as you've seen 
in previous store bytecodes. 


Sams 


Sams.net 
Learning 
Center 


| g 


Stack Operations 


nop -no change- 
Do nothing. 
pop veey aNy =>... 


Pop the top word from the stack. 

pop2 wes, amy2, any1 =>... 

Pop the top two words from the stack. 

dup ..+, any => ..., any, any 

Duplicate the top word on the stack. 

dup2 ..., any2, any1 => ..., any2, any1, any2,any1 

Duplicate the top two words on the stack. 

dup_x1 ..., any2, any1 => ..., amyl, any2,any1 

Duplicate the top word on the stack and insert the copy two words down in the stack. 
dup2_x1 ..., any3, any2, any1 => ..., any2, any1, any3,any2,any1 

Duplicate the top two words on the stack and insert the copies two words down in the stack. 
dup_ x2 ..., any3, any2, any1 => ..., any1, any3,any2,any1 

Duplicate the top word on the stack and insert the copy three words down in the stack. 
dup2_x2 ..., any4, any3, any2, any1 => ..., any2, any1, any4,any3,any2,any1 
Duplicate the top two words on the stack and insert the copies three words down in the stack. 
swap ..., any2, any1 => ..., any1, any2 


Swap the top two elements on the stack. 


Arithmetic Operations 


iadd » V1, v2 => ..., result 
ladd ..., V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
fadd wee, V1, V2 => ..., result 
dadd » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 


vi and v2 must be<type>s. The vs are added and are replaced on the stack by their <type> sum. 
<type> iS, in turn, int, long, float, and double. 
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isub » V1, v2 => ..., result 
lsub .»., V1-word1, vi-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
fsub weey VI, V2 => ..., result 
dsub » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 


vi and v2 must be <type=s. v2 is subtracted from v1, and both vs are replaced on the stack by 
their <type> difference. <type> is, in turn, int, long, float, and double. 


imul » V1, v2 => ..., result 
1lmul » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
fmul weey VI, V2 => ..., result 
dmul » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 


vi and v2 must be<type>s. Both vsare replaced on thestack by their <type> product. <type> is, 
in turn, int, long, float, and double. 


idiv » V1, v2 => ..., result 
ldiv ..., V1-word1, vi-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
fdiv weey VI, V2 => ..., result 
ddiv » V1i-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 


vi and v2 must be <type>s. v2 is divided by v1, and both vs are replaced on the stack by their 
<type> quotient. An attempt to divide by zero resultsin an arithmeticException being thrown. 
<type> is, in turn, int, long, float, and double. 


irem » V1, v2 => ..., result 
lrem ..., V1-word1, vi-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
frem seey VI, V2 => ..., result 
drem » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 


vi and v2 must be <type>s. v2 is divided by v1, and both vs are replaced on the stack by their 
<type> remainder. An attempt to divide by zero results in an ArithmeticException being 
thrown. <type> is, in turn, int, long, float, and double. 


ineg » value => ..., result 
1lneg ,» value-word1, value-word2 => ..., result-word1, result -word2 
fneg ..., Value => ..., result 
dneg ; value-word1, value-word2 => ..., result-word1, result-word2 


value Must be a<type>. It isreplaced on thestack by its arithmetic negation. <type> is, in turn, 
int, long, float, and double 


Note: N ow that you're familiar with the look of the bytecodes, the summaries that 
follow will become shorter and shorter (for space reasons). You can always get any 
desired level of detail from the full virtual machine specification in the latest J ava 
release. 


Logical Operations 


ishl » V1, v2 => ..., result 

1shl » V1-word1, v1-word2, v2 => ..., r-word1, r-word2 

ishr -» V1, v2 => ..., result 

ishr -» Vt-word1, v1-word2, v2 => ..., r-word1, r-word2 

iushr » V1, v2 => ..., result 

lushr » V1-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
For types int and 1ong: arithmetic shift-left, shift-right, and logical shift-right. 

iand -» V1, v2 => ..., result 

land -, Vt-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
ior -» V1, v2 => ..., result 

lor -» V1t-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
ixor -» V1, v2 => ..., result 

lxor -» Vt-word1, v1-word2, v2-word1, v2-word2 => ..., r-word1, r-word2 
For types int and long: bitwise anp, or, and xor. 

Conversion Operations 

i21 » value => ..., result-word1, result -word2 

i2f » value => ..., result 

i2d ; value => ..., result-word1, result -word2 

12i ,» value-word1, value-word2 => ..., result 

12f » value-word1, value-word2 => ..., result 

12d ..., Value-word1, value-word2 => ..., result-word1, result-word2 
f2i ++, Value => ..., result 

f21 ; value => ..., result-word1, result -word2 

f2d » value => ..., result-word1, result -word2 

d2i » value-word1, value-word2 => ..., result 

d21 ; value-word1, value-word2 => ..., result-word1, result -word2 
d2f ,» value-word1, value-word2 => ..., result 

int2byte -.+, Value => ..., result 

int2char ++, Value => ..., result 

int2short -++, Value => ..., result 


T hese bytecodes convert from a value of type<zns> to aresult Of type<rhs>. <1hs> and <rhs> 
can beany of i, 1, ¢,and a, which represent int, long, float, and double, respectively. Thefinal 


three bytecodes have types that are self-explanatory. 


Transfer of one 


ifeq » value => 

ifne » value =>... 

iflt -.+, Value =>... 

ifgt -++, Value =>... 

ifle » value =>... 

ifge » value =>... 
if_icmpeq ..., Value1, value2 =>... 
if_icmpne ..., Valuet, value2 =>... 


if_icmplt -++, value1, value2 =>... 
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if_icmpgt ..., valuel, value2 =>... 
if_icmple ..., Value1, value2 =>... 
if_icmpge ..., Valuel, value2 =>... 
ifnull ..., Value =>... 
ifnonnull ..., Value =>... 


W hen value <re1> oiStruein thefirst set of bytecodes, value1 <rel> value2iStrueinthesecond 
Set, OF value iSnui1 (Or not nui1) in the third, byte1 and byte2 are used to construct a signed 
16-bit offset. Execution proceeds at that offset from the pc. O therwise, execution proceeds at 
thebytecodefollowing. <rez>isoneof eq, ne, 1t, gt, 1e, aNd ge, which represent equal, not equal, 
less than, greater than, less than or equal, and greater than or equal, respectively. 


lcmp ..., V1-word1, v1-word2, v2-word1, v2-word2 => ..., result 
fcmpl weey VI, V2 => ..., result 
dcmpl ., v1-word1, v1-word2, v2-word1, v2-word2 => ..., result 
fcmpg .eey VI, V2 => ..., result 
dcmpg ..., V1-word1, v1-word2, v2-word1, v2-word2 => ..., result 


vi and v2 Must be long, float, OF double. T hey areboth popped from the stack and compared. 
If vi is greater than v2, the int value 1 is pushed onto thestack. If v1 is equal to v2, @ is pushed 
onto the stack. If v1 isless than v2, -1 is pushed onto the stack. For floating-point, if ether v1 
Or v2 iSNan, -1 iS pushed onto the stack for the first pair of bytecodes, +1 for the second pair. 
if_acmpeq ..+, Value1, value2 =>... 

if_acmpne ..., Value1, value2 =>... 

Branch if object references are equal/not equal. value1 and value2 must bereferencesto objects. 
T hey are both popped from the stack. If vaiue1 is equal/not equal to value2, byte1 and byte2 
are used to construct a signed 16-bit offset. Execution proceeds at that offset from the pc. 
Otherwise, execution proceeds at the bytecode following. 

goto -no change- 

goto_w -no change- 

Branch always. byte1 and byte2 (pluSbyte3 and byte4 for goto_w) areused to construct asigned 
16-bit (32-bit) offset. Execution proceeds at that offset from the pc. 

jsr we. => ..., return-address 

jsr-w we. => ..., return-address 

Jump subroutine T headdress of the bytecodeimmediately following the jsr ispushed onto the 
stack. byte1 and byte2 (plus bytes and byte4 for goto_w) are used to construct a signed 16-bit 
(32-bit) offset. Execution proceeds at that offset from the pc. 

ret -no change- 

ret2_w -no change- 

Return from subroutine Local variable byte1 (plus byte2 are assembled into a16-bit index for 
ret_w)inthecurrent] avaframemust contain areturn address. T hecontentsof that local variable 
are written into the pc. 


Note: jsr pushes the address onto the stack, and ret gets it out of a local variable. 
This asymmetry is intentional. The jsr and ret bytecodes are used in theimple 
mentation of J ava’s finally keyword. 


Method Return 


return .+. => [empty] 


Return (void) from method. All valueson theoperand stack arediscarded. T heinterpreter then 
returns control to its caller. 


ireturn ., value => [empty] 
lreturn ., value-word1, value-word2 => [empty] 
freturn ., Value => [empty] 
dreturn ., value-word1, value-word2 => [empty] 
areturn ., value => [empty] 


Return <type> from method. value must bea<type>. T he value is pushed onto thestack of the 
previous execution environment. Any other values on the operand stack are discarded. The 
interpreter then returns control to its caller. <type> is, in turn, int, long, float, double, and 
object reference. 


Note: T he stack behavior of the “return” bytecodes may be confusing to anyone 
expecting the] ava operand stack to be just liketheC stack. J ava’s operand stack 
actually consists of a number of discontiguous segments, each corresponding to a 
method call. A return bytecode empties the J ava operand stack segment corre. 
sponding to the frame of the returning call, but does not affect the segment of any 


parent calls. 
Table J umping 
tableswitch ..., index => ... 


tableswitch IS a variable length bytecode. Immediately after the tableswitch opcode, zero to 
three o bytes are inserted as padding so that thenext byte begins at an address that isamultiple 
of four. After thepadding area series of signed 4-byte quantities: default -offset, low, high, and 
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then (high - low + 1) further signed 4-byte offsets. T hese offsets are treated as a o-based jump 
table. 


T he index Must bean int. If index islessthan 1ow or index isgreater than high, default-offset 
is added to the pc. O therwise, the (index - 1ow)'th dement of the jump table is extracted and 
added to the pc. 


lookupswitch ..., key =>... 


lookupswitch iSavariable-length bytecode. Immediately after the 1ookupswitch opcode, zero to 
three a bytes are inserted as padding so that the next byte begins at an address that is a multiple 
of four. Immediately after the padding is a series of pairs of signed 4-byte quantities. T he first 
pair is special; it contains the default-offset and the number of pairs that follow. Each 
subsequent pair consists of Amatch and an offset. 


The key on thestack must bean int. This key iscompared to each of the matches. If it is equal 
to one of them, the corresponding offset is added to the pc. If the key does not match any of 
the matches, the default -offset is added to the pc. 


Manipulating Object Fields 

putfield ..., handle, value =>... 

putfield ..., handle, value-word1, value-word2 => ... 

Set field in object. byte1 and byte2 areused to construct an index into the constant pool of the 
current class. T he constant pool item is a field reference to a class name and afield name The 
item is resolved to afield block pointer containing the field’s width and offset (both in bytes). 


T hefield at that offset from thestart of theinstance pointed to by hand1e will beset to thevalue 
on thetop of thestack. T hefirst stack pictureisfor 32-bit, and the second for 64-bit widefields. 
T hisbytecodehandlesboth. If handie iSnui1, ANu11PointerException isthrown. If thespecified 
fidd isa static fidd, an IncompatibleClassChangeError Is thrown. 

getfield ..., handle => ..., value 

getfield ..., handle => ..., value-word1, value-word2 

Fetch field from object. byte1 and byte2 are used to construct an index into the constant pool 
of the current class. T he constant pool item will bea field reference to aclass nameand afield 
name. T heitem is resolved to afield block pointer containing thefield’s width and offset (both 
in bytes). 

handle must beareferenceto an object. The value at offset into the object referenced by handle 
replaces handle on thetop of the stack. T he first stack picture is for 32-bit, and the second for 
64-bit wide fields. This bytecode handles both. If the specified field is a static field, an 
IncompatibleClassChangeError is thrown. 


putstatic ..., Value =>... 
putstatic ..., Value-word1, value-word2 => ... 


Set static field in class. byte1 and byte2 are used to construct an index into theconstant pool of 
thecurrent class. The constant pool item will bea field reference to a static fiald of aclass. T hat 
field will beset to havethe vaiue on thetop of thestack. T hefirst stack pictureisfor 32-bit, and 
thesecond for 64-bit widefields. T hisbytecodehandles both. I fthespecified fidd isnot astatic 
field, aN IncompatibleClassChangeError is thrown. 

getstatic weey => 2.2, Value_ 

getstatic weey => ..., Value-word1, value -word2 

Get static field from class. byte1 and byte2 are used to construct an index into theconstant pool 
of the current class. T heconstant pool item will beafield referenceto astatic fidd of aclass. The 
value Of that field is placed on thetop of the stack. T hefirst stack picture is for 32-bit, and the 
second for 64-bit wide fields. T his bytecode handles both. If the specified field isnot astatic 
field, aN IncompatibleClassChangeError Is thrown. 


Method Invocation 


invokevirtual ..., handle, [argi, arg2, ...]], ... =>... 


Invoke instance method based on run/time. T he operand stack must contain a reference to an 
object and somenumber of arguments. byte1 and byte2 areused to construct an index into the 
constant pool of the current class. The item at that index in the constant pool contains the 
complete method signature. A pointer to the object’s method table is retrieved from the object 
reference. | hemethod signature is looked up in the method table. T he method signature is 
guaranteed to exactly match one of the method signatures in the table. 


T heresult of the lookup isan index into the method table of thenamed class that’s used to look 
in the method table of the object’s run/time type, where a pointer to the method block for the 
matched method is found. T he method block indicates the type of method (native, synchro- 
nized, and so on) and the number of arguments (nargs) expected on the operand stack. 


If the method is marked synchronized, the monitor associated with handle is entered. 


T hebase of the local variables array for the new J ava stack frame is set to point to handie on the 
stack, making handie and thesupplied arguments (arg1, arg2, . . .) thefirst nargs local variables 
of the new frame. T he total number of local variables used by the method is determined, and 
theexecution environment of thenew frameispushed after leaving sufficient room for thelocals. 
The base of the operand stack for this method invocation is set to the first word after the 
execution environment. Finally, execution continues with the first bytecode of the matched 
method. 


If handle iS null, @Nul1PointerException is thrown. If during the method invocation a stack 
overflow is detected, a StackOverflowError is thrown. 
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invokenonvirtual ..., handle, [arg1, arg2, ...]] ... =>... 


Invoke instance method based on compiletime type. The operand stack must contain a 
reference (handle) to an object and some number of arguments. byte1 and byte2 are used to 
construct an index into the constant pool of the current class. The item at that index in the 
constant pool contains the complete method signature and class. The method signature is 
looked up in the method table of the class indicated. T he method signature is guaranteed to 
exactly match one of the method signatures in the table. 


The result of the lookup is a method block. The method block indicates the type of method 
(native, synchronized, and so on) and the number of arguments (nargs) expected on the 
operand stack. (T he last three paragraphs are identical to the previous bytecode.) 


invokestatic seey 5 Largi, arg2, ...]] ... =>... 


Invoke class (static) method. The operand stack must contain some number of arguments. 
byte1 and byte2 are used to construct an index into the constant pool of the current class. T he 
item at that index in the constant pool contains the complete method signature and class. T he 
method signatureislooked up in the method table of theclass indicated. Themethod signature 
is guaranteed to match one of the method signatures in the class's method table exactly. 


The result of the lookup is a method block. The method block indicates the type of method 
(native, synchronized, and so on) and the number of arguments (nargs) expected on the 
operand stack. 


If themethod ismarked synchronized, themonitor associated with theclassis entered. (T helast 
two paragraphs are identical to those in invokevirtual, except that no NullPointerException 
can be thrown.) 


invokeinterface ..., handle, [arg1, arg2, ...] =>... 


Invokeinterface method. T heoperand stack must contain areference(handie) to an object and 
some number of arguments. byte1 and byte2 are used to construct an index into the constant 
pool of the current class. The item at that index in the constant pool contains the complete 
method signature. A pointer to the object’s method table is retrieved from the object reference. 
The method signature is looked up in the method table. T he method signature is guaranteed 
to exactly match one of the method signatures in the table. 


The result of the lookup is a method block. The method block indicates the type of method 
(native, synchronized, and so on) but, unlike the other “invoke” bytecodes, the number of 
available arguments (nargs) istaken from byte3; byte4 is reserved for future use. (T helast three 
paragraphs are identical to those in invokevirtual.) 


Exception Handling 


athrow ..., handle => [undefined] 


T hrow exception. handie must beahandleto an exception object. T hat exception, which must 
beasubclassof Throwable, isthrown. T hecurrent] avastack frameissearched for themost recent 
catch Clause that handles the exception. If amatching “catch-list” entry is found, the pc is reset 
to the address indicated by the catch-list pointer, and execution continues there. 


If no appropriate catch clause is found in the current stack frame, that frame is popped and the 
exception is rethrown, starting the process all over again in the parent frame. If handie iS nu11, 
then a NullPointerException is thrown instead. 


Miscellaneous O bject Operations 


new -+. => ..., handle 


Create new object. byte1 and byte2 areused to construct an index into the constant pool of the 
current class. T heitem at that index should beaclassnamethat can beresolved to aclass pointer, 
class. A new instanceof that classisthen created and areference(hand1e) fortheinstanceisplaced 
on the top of the stack. 


checkcast ...; handle => ..., [handle};...] 


M ake sure object is of given type. handle must be areference to an object. byte1 and byte2 are 
used to construct an index into the constant pool of the current class. T he string at that index 
of the constant pool is presumed to be aclassname that can be resolved to aclass pointer, class. 


checkcast determineswhether handle can becast to areferenceto an object of that class. (A nu11 
handle can be cast to any class.) If nandie can be legally cast, execution proceeds at the next 
bytecode, and the handle for handie remains on the stack. If not, a classcastException iS 
thrown. 


instanceof ..., handle => ..., result 


Determine whether object is of given type. handle must be areference to an object. byte1 and 
byte2 areused to construct an index into theconstant pool of thecurrent class. T hestring at that 
index of the constant pool is presumed to bea classname that can be resolved to a class pointer, 
Class. 


If handle iSnul1, the result iS(false). Otherwise, instanceof determines whether handle can 
be cast to a reference to an object of that class. The resuit iS 1 (true) if it can, and o (false) 
otherwise. 
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Monitors 


monitorenter ..., handle =>... 


Enter monitored region of code. handle must be a reference to an object. The interpreter 
attemptsto obtain exclusiveaccess via alock mechanism to handie. If another thread already has 
handle locked, thecurrent thread waits until the handie isunlocked. Ifthecurrent thread already 
has handle locked, execution continues normally. If handie has no lock on it, this bytecode 
obtains an exclusive lock. 


monitorexit ..., handle =>... 


Exit monitored region of code. handle must bea reference to an object. Thelock on handle is 
released. If thisis the last lock that this thread has on that handie (onethread is allowed to have 
multiple locks on a single handle), other threads that are waiting for handie are allowed to 
proceed. (A nui1 in either bytecode throws nu11PointerException.) 


D ebugging 
breakpoint -no change- 


Call breakpoint handler. The breakpoint bytecode is used to overwrite a bytecode to force 
control temporarily back to the debugger prior to the effect of the overwritten bytecode. T he 
original bytecode’s operands (if any) are not overwritten, and the original bytecode is restored 
when the breakpoint bytecode is renoved. 


The _ quick B ytecodes 


The following discussion, straight out of theJ ava virtual machine documentation, shows you 
an example of the cleverness mentioned earlier that’s needed to makea bytecodeinterpreter fast: 


The following set of pseudo-bytecodes, suffixed by quick, areall variants of standard 
Java bytecodes. T hey are used by the run-time to improve the execution speed of the 
bytecode interpreter. They aren’t officially part of the virtual machine specification 
and are invisible outside aJ ava virtual machine implementation. H owever, inside that 
implementation they have proven to bean effective optimization. 


First, you should know that javac still generates only non-_quick bytecodes. Second, 
all bytecodes that have a_quick variant reference the constant pool. When _quick 
optimization is turned on, each non-_quick bytecode (that has a_quick variant) 
resolves the specified item in the constant pool, signals an error if the item in the 
constant pool could not be resolved for some reason, turns itself into the quick 
variant of itself, and then performs its intended operation. 
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Thisis identical to the actions of the non-_quick bytecode, except for the step of 
overwriting itself with its quick variant. The _quick variant of a bytecode assumes 
that the item in the constant pool has already been resolved, and that this resolution 
did not produce any errors. It simply performs the intended operation on the resolved 
item. 


Thus, as your bytecodes are being interpreted, they are automatically getting faster and faster! 
H ere are all the quick variants in the current Java run-time: 


ldc1_quick 
ldc2_quick 
ldc2w_quick 


anewarray_quick 
multinewarray_quick 


putfield_ quick 

putfield2_quick 
getfield_quick 

getfield2_quick 
putstatic_quick 
putstatic2_quick 
getstatic_quick 
getstatic2_quick 


invokevirtual_quick 
invokevirtualobject_quick 
invokenonvirtual_quick 
invokestatic_quick 
invokeinterface_quick 


new_quick 

checkcast_quick 

instanceof_quick 

If you’d like to go back in today’s lesson and look at what each of these does, you can find the 
nameof theoriginal bytecodeon which a_quick variant isbased by simply removing the_quick 
from itsname. T he bytecodes putstatic, getstatic, putfield, and getfield havetwo _quick 
variants each, one for each stack picturein their original descriptions. invokevirtual has two 
variants: one for objects and one for arrays to do fast lookupsin javala. object). 


Note: O nelast note on the quick optimization, regarding the unusual handling of 
the constant pool (for detail fanatics only): 


W hen a class is read in, an array constant_pool[] Of SZ@nconstants IS created and 
assigned to a field in the class. constant_poo1[o] is set to point to a dynamically 
allocated array that indicates which fields in the constant_poo1 have already been 
resolved. constant_pool[1] through constant_pool[nconstants - 1] areset to 
point at the “type” field that corresponds to this constant item. 
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When a bytecode is executed that references the constant pool, an index is gener- 
ated, and constant_pool[a] is checked to see whether the index has already been 
resolved. If so, the value of constant_pool[ index] is returned. If not, the value of 
constant_pool[index] iS resolved to be the actual pointer or data, and overwrites 
whatever value was already in constant_pool[ index]. 


The .class File Format 


You won't begiven the entire .class file format here, only ataste of what it’s like. (You can read 
all about it in the release documentation.) It’s mentioned here because it is one of the parts of 
J avathat needsto bespecified carefully if all J avaimplenentationsareto becompatiblewith one 
another, and if] avabytesareexpected to travel across arbitrary networks— to and from arbitrary 
computers and operating systens— and yet arrive safely. 


Therest of this section paraphrases, and extensively condenses, the latest (alpha) release of the 
.class documentation. 


.Class files are used to hold the compiled versions of both Java classes and Java interfaces. 
Compliant J ava interpreters must be capable of dealing with all .class files that conform to the 
following specification. 


A Java .class file consists of a stream of 8-bit bytes. All 16-bit and 32-bit quantities are 
constructed by reading in two or four 8-bit bytes, respectively. T he bytes are joined together in 
big-endian order. (U se@java.io.DataInput and java. io.DataOutput to read and writeclassfiles.) 


T he class fileformat is presented below as aseries of C-struct-like structures. H owever, unlike 
aC struct, thereisno padding or alignment between pieces of the structure, each field of the 
structuremay beof variablesize, and an array may beof variablesize(in thiscase, somefield prior 
to the array gives the array’s dimension). The types u1, u2, and u4 represent an unsigned 
one., two-, or four-byte quantity, respectively. 


Attributesareused at several different placesin the.classformat. All attributeshavethefollowing 
format: 
GenericAttribute_info { 

u2 attribute_name; 

u4 attribute_length; 

ul info[attribute_length]; 
} 
The attribute_name iS a 16-bit index into the class’s constant pool; the value of 
constant_pool[attribute_name] iS a string giving the name of the attribute The field 
attribute_length givesthelength of thesubsequent information in bytes. T hislength doesnot 
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include the four bytes needed to storeattribute_name and attribute _length. In thefollowing 
text, whenever an attribute is required, names of all the attributes that are currently understood 
arelisted. In thefuture, moreattributes will be added. Classfilereaders are expected to skip over 
and ignore the information in any attributes that they do not understand. 


The following pseudo-structure gives a top-level description of the format of a class file: 


ClassFile { 
u4 magic; 
u2 minor_version 
u2 major_version 
u2 constant_pool_count; 
cp_info constant_pool[constant_pool_count - 1]; 
u2 access_ flags; 
u2  this_class; 
u2 super_class; 
u2 interfaces_count; 
u2 interfaces[interfaces_count]; 
u2 fields count; 


field_info fields[fields_count]; 
u2 methods_count; 
method_info methods[methods_ count]; 


u2 attributes count; 
attribute_info attributes[attribute_count]; 


} 
H ere’s one of the smaller structures used: 


method_info { 
u2 access flags; 
u2 name_index; 
u2 signature_index; 
u2 attributes count; 
attribute_info attributes[attribute_ count]; 


} 
Finally, here’s a sample of one of the later structures in the .class file description: 


Code_attribute { 
u2 attribute_name_index; 
u2 attribute_length; 
ul max_stack; 
u1 max_locals; 
u2 code_length; 
ul code[code_length]; 
u2 exception_table_length; 
{ u2_ — start_pc; 
u2_—s end_pc; 
u2_ ~—ihandler_pc; 
u2_ ~~ catch_type; 
} exception_table[exception_table_ length]; 
u2 attributes count; 
attribute_info attributes[attribute count]; 
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N one of this is meant to be completely comprehensible (though you might be able to guess at 
what alot of thestructuremembersarefor), but just suggestive of thesort of structures that live 
inside .classfiles. Becausethe compiler and run-timesourcesare available, you can always begin 
with them if you actually have to read or write .classfiles yourself. T hus, you don’t need to have 
a deep understanding of the details, even in that case. 


Method Signatures 
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Because method signatures are used in .class files, now is an appropriate time to explore them 
in the detail promised on earlier days— but they're probably most useful to you when writing 
the native methods of yesterday's lesson. 


NEWee A Sgnatureisa string representing the type of a method, fied, or array. 
TERM 


A field signature represents the value of an argument to a method or the value of a variable and 
isaseries of bytesin the following grammar: 


<field signature> : 
<field type> 
<base_type> 
<object_type> 
<array_type> 
<optional_size> 


<field _type> 

<base_type> | <object_type> | <array_type> 
BCD ek oy) Sit 

L <full.ClassName> ; 

[ <optional_size> <field_type> 

[0-9]* 


H erearethemeanings of thebasetypes: B (byte), c (char), D (double), F (float), (int), J (long), 
s (short), and Z (boolean). 


A return-type signature represents the return value from amethod and isa series of bytesin the 
following grammar: 


<return signature> := <field type> | V 


The character v (voia) indicates that the method returns no value. O therwise, the signature 
indicates the type of thereturn value. An argument signature represents an argument passed to 
a method: 


<argument signature> := <field type> 


Finally, amethod signaturerepresentstheargumentsthat themethod expects, and thevaluethat 
it returns: 


<method_signature> 
<arguments signature> 


(<arguments signature>) <return signature> 
<argument signature>* 


Let’s try out the new rules: a method called complexmethoa() in the class 
my.package.name.ComplexClass takes three arguments—a long, a boolean, and a two- 
dimensional array of shortS— andreturnsthis. T hen, (JZ[[S)Lmy.package.name.ComplexClass; 
is its method signature. 


A method signature is often prefixed by thename of the method, or by its full package (using 
an underscore in the place of dots) and its class name followed by aslash and thenameof the 
method, to form a complete method sgnature (You saw several of these generated in stub 
comments yesterday.) N ow, at last, you have the full story! T hus, the following: 


my_package_name_ComplexClass/complexMethod(JZ[[S)Lmy.package.name.ComplexClass; 


is the full, complete method signature of method complexmethod(). (Phew!) 


T he Garbage Collector 


Decades ago, programmers in both the Lisp and the Smalltalk community realized how 
extremely valuable it isto be able to ignore memory deallocation. T hey realized that, although 
allocation is fundamental, deallocation is forced on the programmer by the laziness of the 
systen— it should be able to figure out what is no longer useful, and get rid of it. In relative 
obscurity, these pioneering programmers developed a whole series of garbage collectors to 
perform thisjob, each getting moresophisticated and efficient asthe years went by. Finally, now 
that the mainstream programming community has begun to recognize the value of this 
automated technique, J ava can become thefirst really widespread application of thetechnology 
those pioneers developed. 


The Problem 


Imagine that you’re a programmer in a C-like language (probably not too difficult for you, 
because these languages are the dominant ones right now). Each time you create something, 
anything, dynamically in such alanguage, you arecompletely responsible for tracking thelife of 
this object throughout your program and mentally deciding when it will be safe to deallocate 
it. This can be quite a difficult (sometime impossible) task, because any of the other libraries or 
methods you've called might have “squirreled away” a pointer to the object, unbeknownst to 
you. W hen it becomes impossibleto know, you simply chooseneve to deallocatethe object, or 
at least to wait until every library and method call involved hascompleted, which could benearly 
as long. 


The uneasy feeling you get when writing such code is a natural, healthy response to what is 
inherently an unsafe and unreliablestyle of programming. If you havetrenendousdiscipline— 
and so does everyone who writes every library and method you call— you can, in principle, 
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survivethisresponsibility without too many mishaps. But aren’t you human?Aren’t they?T here 
must be some small slipsin this perfect discipline due to error. What's worse, such errors are 
virtually undetectable, asanyone who’stried to hunt down astray pointer problem in C will tell 
you. W hat about the thousands of programmers who don’t have that sort of discipline? 


Another way to ask this question is: Why should any programmers be forced to have this 
discipline, when it is entirely possible for the system to remove this heavy burden from their 
shoulders? 


Software engineering estimates have recently shown that for every 55 lines of production C-like 
codein the world, thereis one bug. T hismeans that your electric razor has about 80 bugs, and 
your TV, 400. Soon they will have even more, because the size of this kind of embedded 
computer softwareis growing exponentially. W hen you begin to think of how much C -likecode 
isin your car’s engine, it should give you pause. 


M any of theseerrorsare dueto themisuseof pointers, by misunderstanding or by accident, and 
to theearly, incorrect freeing of allocated objects in memory. J ava addresses both of these— the 
former, by eliminating explicit pointers from the J ava language altogether and the latter, by 
including, in every J ava system, a garbage collector that solves the problem. 


The Solution 


Imagine arun-time system that tracks each object you create, notices when the last reference to 
it has vanished, and frees the object for you. H ow could such a thing actually work? 


O nebrute-force approach, tried early in the days of garbage collecting, isto attach a reference 
counter to every object. When the object is created, the counter is set to 1. Each time anew 
reference to the object is made, the counter is incremented, and each time such a reference 
disappears, the counter is decremented. Because all such references are controlled by the 
language— as variables and assignments, for example— thecompiler can tell whenever an object 
reference might be created or destroyed, just asit doesin handling the scoping of local variables, 
and thusit can assist with this task. T he system itself “holds onto” aset of root objects that are 
considered too important to be freed. T he class object is one example of such aV.1.P. object. 
(V.1.0..?) Finally, all that’s needed is to test, after each decrement, whether the counter has hit 
a. If it has, the object is freed. 


If you think carefully about this approach, you can soon convince yourself that it is definitely 
correct when it decides to free anything. It isso simplethat you can immediately tell that it will 
work. T he low-level hacker in you might also feel that if it’s that simple, it’s probably not fast 
enough to run at the lowest level of the system— and you'd be right. 


Think about all the stack frames, local variables, method arguments, return values, and local 
variables created in the course of even afew hundred milliseconds of aprogram’slife. For each 
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of thesetiny, nano-stepsin the program, an extra increment— at best— or decrement, test, and 
deallocation— at worst— will be added to the running time of the program. In fact, the first 
garbage collectors were slow enough that many predicted they could never be used at all! 


Luckily, awholegeneration of smart programmershasinvented a big bag of tricksto solvethese 
overhead problems. O netrick isto introduce special “transient object” areas that don’t need to 
bereferencecounted. T hebest of thesegenerational scavenging garbage collectorstoday can take 
lessthan 3 percent of the total time of your program— aremarkablefeat if you realizethat many 
other language features, such as loop overheads, can be as large or larger! 


T hereare other problems with garbage collection. If you are constantly freeing and reclaiming 
space in a program, won't the heap of objects soon become fragmented, with small holes 
everywhereand no room to createnew, large objects? Because the programmer isnow freefrom 
the chains of manual deallocation, won't they create even more objects than usual? 


W hat’s worse, thereis another way that this simple reference counting schemeis inefficient, in 
space rather than time. If along chain of object references eventually comes full circle, back to 
thestarting object, each object’s reference count renains at least 1 forever. N one of these objects 
will ever be freed! 


T ogether, these problemsimply that a good garbage collector must, every oncein awhile, step 
back to compact or to clean up wasted memory. 


NEWee Compaction occurs when a garbage collector steps back and reorganizes 
TERM memory, eliminating the holes created by fragmentation. Compacting 
memory is simply a matter of repositioning objects one-by-one into anew, 
compact grouping that places them all in a row, leaving all the free memory in the 
heap in one big piece. 


Cleaning up the circular garbage still lying around after reference counting is called 
marking and sweeping. A mark-and-sweep of memory involves first marking every root 
object in the system and then following all the object references inside those objects to 
new objects to mark, and so on, recursively. Then, when you have no more references 
to follow, you “sweep away” all the unmarked objects, and compact memory as 
before. 


T hegood newsisthat thissolvesthespaceproblensyou werehaving. T hebad newsisthat when 
thegarbage collector “steps back” and doesthese operations, anontrivial amount of time passes 
during which your program isunableto run— all itsobjectsarebeing marked, swept, rearranged, 
and so forth, in what seemslikean uninterruptible procedure. Your first hint to asolution isthe 
word “seems.” 
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Garbage collecting can actually be done alittle at a time, between or in parallel with normal 
program execution, thus dividing up the large time needed to “step back” into numerous so- 
small-you-don’t-notice them chunks of timethat happen between thecracks. (O f course, years 
of smart thinking went into the abstruse algorithms that make all this possible!) 


Onefinal problem that might worry you alittle has to do with these object references. Aren’t 
these “pointers” scattered throughout your program and not just buried in objects? Even if 
they’reonlyin objects, don’t they haveto bechanged whenever theobject they point to ismoved 
by these procedures? T heanswer to both of these questionsisaresounding yes, and overcoming 
them is the final hurdle to making an efficient garbage collector. 


T herearereally only two choices. T hefirst, bruteforce, assumesthat all the memory containing 
object references needs to be searched on a regular basis, and whenever the object references 
found by this search match objects that have moved, the old referenceis changed. T hisassumes 
that there are “hard” pointers in the heap’s memory— ones that point directly to other objects. 
By introducing various kinds of “soft” pointers, including pointers that are like forwarding 
addresses, the algorithm improves greatly. Although these brute-force approaches sound slow, 
it turns out that modern computers can do them fast enough to be useful. 


Note: You might wonder how the brute-force techniques identify object references. 
In early systems, references were specially tagged with a “pointer bit,” so they could 
be unambiguously located. N ow, so-called conservative garbage collectors simply 
assume that if it looks like an object reference, it is— at least for the purposes of the 
mark and sweep. Later, when actually trying to update it, they can find out 
whether it really is an object reference or not. 


T hefinal approach to handling object references, and theone] ava currently uses, is also one of 
the very first ones tried. It involves using 100 percent “soft” pointers. An object reference is 
actually a handle, sometimes call an “OOP,” to the real pointer, and a large object table exists 
to map these handles into the actual object reference. Although this does introduce extra 
overhead on almost every object reference (some of which can be eliminated by clever tricks, as 
you might guess), it’snot too high a price to pay for thisincredibly valuable level of indirection. 


This indirection allows the garbage collector, for example, to mark, sweep, move, or examine 
one object at atime Each object can beindependently moved “out from under” arunning] ava 
program by changing only the object table entries. T his not only allows the “step back” phase 
to happen in thetiniest steps, but it makes a garbage collector that runsliterally in parallel with 
your program much easier to write. T his is what the J ava garbage collector does. 


| Warning: You need to be very careful about garbage collection when you're doing 
a critical, real-time programs (such as those mentioned yesterday that legitimately 

 ~ require native methods)— but how often will your Java code be flying a commercial 

airliner in real-time, anyway? 


J ava’s Parallel Garbage Collector 


Java applies almost all these advanced techniques to give you a fast, efficient, parallel garbage 
collector. Running in a separate thread, it cleans up the} ava environment of almost all trash (it 
is conservative), silently and in the background, is efficient in both space and time, and never 
steos back for morethan an unnoticeably small amount of time. You should never need to know 
it’s there. 


By the way, if you want to force a full mark-and-sweep garbage collection to happen soon, you 
can do so simply by calling thesystem.gc() method. You might want to do thisif you just freed 
up amajority of theheap’s memory in circular garbage, and want it all taken away quickly. You 
might also call this whenever you’reidle, asahint to the system about when it would be best to 
come and collect the garbage. T his “meta knowledge’ is rarely needed by the systen, however. 


Ideally, you'll never notice the garbage collector, and all those decades of programmers beating 
their brains out on your behalf will simply let you sleep better at night— and what’s wrong with 
that? 


T he Security Story 


Speaking of sleeping wall at night, if you haven’t steoped back yet and said, “You mean J ava 
programs will berunning rampant on the! nternet!?!” you better do so now, for itis alegitimate 
concern. In fact, itisoneof themajor technical stumbling blocks (theothersbeing mostly social 
and economic) to achieving thedream of ubiquity and codesharing mentioned earlier in today’s 
lesson. 


Why You Should Worry 


Any powertul, flexible technology can be abused. As the Net becomes mainstream and 
widespread, it, too, will be abused. Already, there have been many blips on the security radar 
screens of those of us who worry about such things, warning that (at least until today), not 
enough attention has been paid by the computer industry (or themedia) to solving someof the 
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problemsconstructively that thisnew world bringswith it. O neofthebenefitsof solvingsecurity 
once and for all will be a flowering unseen beforein the virtual communities of the N et; whole 
new economiesbased on people’sattention and creativity will springto life, rapidly transforming 
our world in new and positive ways. 


T he downside to all this new technology, is that we (or someone!) must worry long and hard 
about how to make the playgrounds of the future safefor our children, and for us. Fortunately, 
Java is a big part of the answer. 


Why You Might Not Have To 


W hat gives me any confidence that the] ava language and environment will besafe, that it will 
solve the technically daunting and extremely thorny problems inherent in any good form of 
security, especially for networks? 


O nesimplereason isthehistory of thepeople, and thecompany, that created J ava.M any of them 
are the very smart programmers referred to throughout the book, who helped pioneer many of 
theideas that make] ava great and who have worked hard over the decades to make techniques 
such as garbage collection a mainstream reality. They are technically capable of tackling and 
solving the hard problems that need to be solved. In particular, from discussions with C huck 
M cM anis, oneof] ava’ssecurity gurus, | haveconfidencethat hehasthought through thesehard 
problems deeply, and that he knows what needs to be done 


Sun Microsystems, the company, has been pushing networks as the central theme of all its 
software for more than a decade. Sun has the engineers and the commitment needed to solve 
these hard problems, because these same problems are at the very center of both its future 
businessand itsvision of thefuture, in which networkingisthecenter of everything— and global 
networks are nearly useless without good security. J ust this year, Sun has advanced the state of 
the art in easy-to-use Internet security with its new SunScreen products, and it has assigned 
W hitfield D iffieto overseethem, who istheman who discovered theunderlyingideason which 
essentially all interesting forms of modern encryption are based. 


Enough on “deep background.” W hat does the} ava environment provideright now that helps 
us feel secure? 


J ava’s Security Model 


Java protects you against potential “nasty” J ava code via a series of interlocking defenses that, 
together, form an imposing barrier to any and all such attacks. 
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ness. If you’re the kind of person who blindly downloads binary executables from 
&) your Internet browser and runs them, you need read no further! You are already in 
more danger than J ava will ever pose. 


y Caution: Of course, no onecan protect you from your own ignorance or careless- 


Asauser of this powerful new medium, the Internet, you should educate yourself to 
the possible threats this new and exciting world entails. In particular, downloading 
“auto running macros’ or reading e-mail with “executable attachments” is just as 
much a threat as downloading binaries from the N et and running them. 


Java does not introduce any new dangers here, but by being the first mainstream use 
of executable and mobile code on theN et, it is responsible for making people 
suddenly aware of the dangers that have always been there J avais already, as you 
will soon see, much less dangerous than any of these common activities on the N et, 
and can be made safer still over time. M ost of these other (dangerous) activities can 
never be made safe. So please, do not do them! 


A good rule of thumb on the N et is: Don’t download anything that you plan to 
execute (or that will be automatically executed for you) except from someone (or 
some company) you know well and with whom you've had positive, personal 
experience. If you don’t care about losing all the data on your hard drive, or about 
your privacy, you can do anything you like, but for most of us, this rule should be 
law. 


Fortunately, Java allows you to relax that law. You can run Java applets from 
anyone, anywhere, in complete safety. 


Java's powerful security mechanismsact at four different levels of the system architecture. First, 
the] ava language itself was designed to be safe, and the] ava compiler ensures that source code 
doesn’t violate these safety rules. Second, all bytecodes executed by the run-time are screened 
to be sure that they also obey these rules. (T his layer guards against having an altered compiler 
produce code that violates the safety rules.) Third, the class loader ensures that classes don’t 
violate name space or access restrictions when they are loaded into the system. Finally, API- 
specific security prevents applets from doing destructivethings. T his final layer deoends on the 
security and integrity guarantees from the other three layers. 


Let's now examine each of these layers in turn. 
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The Language and the Compiler 


T he] ava language and its compiler are the first line of defense. J ava was designed to be a safe 
language. 


M ost other C-like languages have facilities to control access to “objects,” but also have ways to 
“forge” accessto objects (or to parts of objects), usually by (mis-)using pointers. T hisintroduces 
two fatal security flawsto any system built on theselanguages. O neisthat no object can protect 
itself from outside modification, duplication, or “spoofing” (others pretending to be that 
object). Another isthat alanguagewith powerful pointersismorelikely to haveserious bugsthat 
compromise security. T hese pointer bugs, where a “runaway pointer” starts modifying some 
other object's memory, were responsible for most of the public (and not-so-public) security 
problems on the Internet this past decade. 


J avaeliminatesthesethreats in onestrokeby eliminating pointersfrom thelanguage altogether. 
T herearestill pointersof akind— object references— but thesearecarefully controlled to besafe: 
they are unforgeable, and all casts are checked for legality before being allowed. In addition, 
powerful new array facilitiesin J avanot only help to offset thelossof pointers, but add additional 
safety by strictly enforcing array bounds, catching more bugs for the programmer (bugs that, in 
other languages, might lead to unexpected and, thus, bad-guy-exploitable problems). 


The language definition, and the compilers that enforce it, create a powerful barrier to any 
“nasty” J ava programmer. 


Becausean overwhelming majority of the“net-savvy” softwareon thel nternet may soon be] ava, 
itssafelanguage definition and compilershelp to guaranteethat most of thissoftwarehasasolid, 
secure base. W ith fewer bugs, N et software will be more predictable— a property that thwarts 
attacks. 


Verifying the B ytecodes 


W hat if that “nasty” programmer gets alittle more determined, and rewrites the] ava compiler 
to suit his nefarious purposes? T he avarun-time, getting thelion’s share of its bytecodes from 
the N et, can never tell whether those bytecodes were generated by a “trustworthy” compiler. 
Therefore, it must verify that they meet all the safety requirements. 


Beforerunning any bytecodes, therun-time subjects then to a rigorous series of tests that vary 
in complexity from simple format checks all the way to running a theorem prover, to make 
certain that they are playing by the rules. T hese tests verify that the bytecodes do not forge 
pointers, violate access restrictions, access objects as other than what they are(InputStreams are 
always used aS InputStreams, and never as anything else), call methods with inappropriate 
argument values or types, nor overflow the stack. 
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Consider the following J ava code sample: 


public class VectorTest { 
public int array[]; 


public int sum() { 


int[] localArray = array; 
int sum = 0 
for (int i = localArray.length; --i >= 0; ) 


sum += localArray[i]; 
return sum; 


} 
} 
T he bytecodes generated when this code is compiled look something like the following: 

aload_0 Load this 

getfield #10 Load this.array 
astore_1 Store in localArray 
iconst_0 Load o 

istore 2 Storein sum 
aload_1 Load 1localArray 
arraylength Gets its length 
istore 3 Storein i 

A: iinc 3 -1 Subtract 1 from i 
iload 3 Load i 

iflt B Exit loop if <o 
iload_2 Load sum 

aload_1 Load 1localArray 
iload 3 Load i 

iaload Load localArray[i] 
iadd Add sum 

istore 2 Store in sum 

goto A Do it again 

B: iload_2 Load sum 

ireturn Return it 
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Note: T he excellent examples and descriptions in this section of the book are 
paraphrased from the tremendously informative security paper in the (alpha) J ava 
release. |’d encourage you to read whatever the latest version of this document is in 
newer releases, if you want to follow the ongoing J ava security story. 


E xtra T ype Information and R equirements 

J ava bytecodes encode moretype information than isstrictly necessary for the interpreter. Even 
though, for example, thea1oad and iload opcodesdo exactly thesamething, aload isalwaysused 
to load an object referenceand i1oad used to load an integer. Somebytecodes(such as getfield) 
include a symbol table reference— and that symbol tablehas even moretypeinformation. T his 
extratypeinformation allowstherun-timesystem to guarantee that J ava objects and data aren't 
illegally manipulated. 


Conceptually, before and after each bytecode is executed, every slot in the stack and every local 
variable has some type. T his collection of type information— all the slots and local variables— 
iscalled thetype state of the execution environment. An important requirement of the] ava type 
state is that it must be determinable statically by induction— that is, before any program code 
is executed. As a result, as the run-time systems reads bytecodes, each is required to have the 
following inductive property: given only thetypestate before the execution of the bytecode, the 
type state afterward must be fully determined. 


Given “straight-line” bytecodes (no branches), and starting with a known stack state, the state 
of each slot in the stack is therefore always known. For example, starting with an empty stack: 


iload_1 Load integer variable. Stack type state is 1. 
iconst 5 Load integer constant. Stack type state is 11. 
iadd Add two integers, producing an integer. Stack type state is 1. 


Note: Smalltalk and PostScript bytecodes do not have this restriction. T heir more 
dynamic type behavior does create additional flexibility in those systems, but J ava 
needs to provide a secure execution environment. It must therefore know all types 
at all times in order to guarantee a certain level of security. 


Another requirenent made by the] ava run-time is that when a set of bytecodes can take more 
than one path to arrive at thesame point, all such paths must arrive there with exactly the same 
typestate. T hisisastrict requirement, and implies, for example, that compilers cannot generate 
bytecodes that load all the elements of an array onto thestack. (Becauseeach timethrough such 
aloop thestack’stypestatechanges, thestart of theloop— “thesamepoint” in multiple paths— 
would have more than one type state, which is not allowed). 


The Verifier 

Bytecodes are checked for compliance with all these requirenents, using the extra type 
information in a.classfile, by apart of therun-timecalled theverifie. It examines each bytecode 
in turn, constructing the full type state as it goes, and verifies that all the types of parameters, 
arguments, and results are correct. Thus, the verifier acts as a gatekeeper to your run-time 
environment, letting in only those bytecodes that pass muster. 


having a correctly implemented (no bugs, intentional or otherwise) run-time 

a system. As of this writing, only Sun is producing J ava run-times, and theirs are 
secure. In the future, however, you should be careful when downloading or buying 
another company’s (or individual’s) version of the] ava run-time environment. 
Eventually, Sun will implement validation suites for run-times, compilers, and so 
forth to be sure that they are safe and correct. In the meantime, caveat emptor ! Your 
run-time is the base on which all the rest of J ava’s security is built, so make sureit is 
a good, solid, secure base. 


y Warning: T he verifier is the crucial piece of J ava’s security, and it deoends on your 


W hen bytecodes have passed the verifier, they are guaranteed not to: cause any operand stack 
under- or overflows; use parameter, argument, or return typesincorrectly; illegally convert data 
from onetypeto another (from an integer to apointer, for example); nor accessany object’sfields 
illegally (that is, the verifier checks that the rules for public, private, package, and protected 
are obeyed). 


Asan added bonus, because the interpreter can now count on all these facts being true, it can 
run much faster than before. All therequired checks for safety havebeen doneup front, so it can 
run at full throttle In addition, object referencescan now betreated as capabilities, becausethey 
are unforgeable— capabilities allow, for example, advanced security models for file |/O and 
authentication to be safely built on top of Java. 
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Note: Because you can now trust that a private variable really is private, and that 
no bytecode can perform some magic with casts to extract information from it 
(such as your credit card number), many of the security problems that might arise 
in other, less safe environments simply vanish! T hese guarantees also make erecting 
barriers against destructive applets possible, and easier. Because the J ava systen 
doesn’t have to worry about “nasty” bytecodes, it can get on with creating the other 
levels of security it wants to provide to you. 


The Class Loader 
The class loader is another kind of gatekeeper, albeit a higher-level one. The verifier was the 
security of last resort. T he class loader is the security of first resort. 


W hen anew classisloaded into thesystem, it must comefrom oneof several different “realms.” 
In thecurrent release, there arethree possible realms: your local computer, the firewall-guarded 
local network on which your computer is located, and the Internet (the global N et). Each of 
these realms is treated differently by the class loader. 


Note: Actually, there can be as many realms as your desired level of security (or 
paranoia) requires. T his is because the class loader is under your control. Asa 
programmer, you can make your own class loader that implements your own 
peculiar brand of security. (T hisis a radical step: you may have to give the users of 
your program a whole bunch of classes— and they give you a whole lot of trust— to 
accomplish this.) 


As auser, you can tell your J ava-aware browser, or Java system, what realm of 
security (of the three) you'd like it to implement for you right now or from now 
on. 


Asasysten administrator, Java has global security policies that you can set up to 
help guide your users to not “give away the store” (that is, set all their preferences 
to be unrestricted, promiscuous, “hurt me please!”). 


In particular, the classloader never allowsa classfrom a “less protected” realm to replace a class 
from amore protected realm. T hefile system’s!/O primitives, about which you should bevery 
worried (and rightly so), areall defined in alocal J ava class, which meansthat they all livein the 
local-computer realm. Thus, no class from outside your computer (from either the supposedly 
trustworthy local network or from the Internet) can take the place of these classes and “spoof” 


J avacodeinto using “nasty” versions of theseprimitives. In addition, classesin onerealm cannot 
call upon themethodsof classesin other realms, unlessthoseclasseshaveexplicitly declared those 
methods public. T hisimplies that classes from other than your local computer cannot even see 
the file system |/O methods, much less call them, unless you or the systen wants them to. 


In addition, every new applet loaded from the network is placed into a separate package like 
namespace. T his means that applets are protected even from each other! N o applet can access 
another’s methods (or variables) without its cooperation. Applets from inside the firewall can 
even be treated differently from those outside the firewall, if you like. 


Note: Actually, it’s all a little more complex than this. In the current release, an 
applet isin a package “namespace” along with any other applets from that source. 
This source, or origin, is most often a host (domain name) on the Internet. T his 
special “subrealm” is used extensively in the next section. Depending on where the 
source is located, outside the firewall (or inside), further restrictions may apply (or 
be removed entirely). T his mode is likely to be extended in future releases of J ava, 
providing an even finer degree of control over which classes get to do what. 


T heclassloader essentially partitionstheworld of J avaclassesinto small, protected little groups, 
about which you can safely make assumptions that will alwaysbetrue. T histypeof predictability 
is the key to well-behaved and secure programs. 


You've now seen the full lifetime of a method. It starts as source code on some computer, is 
compiled into bytecodes on some (possibly different) computer, and can then travel (asa .class 
file) into any file system or network anywherein the world. When you run an applet in aj ava- 
aware browser (or download aclass and run it by hand using java), the method's bytecodes are 
extracted from its .classfileand carefully looked over by theverifier. O ncethey aredeclared safe, 
the interpreter can execute then for you (or a code generator can generate native binary code 
for them using either the “just-in-time” compiler or java2c, and then run that native code 
directly). 


At each stage, more and more security is added. T he final level of that security is the] ava class 
library itself, which has several carefully designed classes and APIs that add thefinal touches to 
the security of the system. 


The Security Manager 

SecurityManager ISaNn abstract Classthat wasrecently added to the] avasystem to collect, in one 
place, all the security policy decisionsthat the system has to makeasbytecodesrun. You learned 
beforethat you can create your own class loader. In fact, you may not haveto, because you can 
subclass securityManager to perform most of the same customizations. 
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An instance of some subclass of securitymManager is always installed as the current security 
manager. It has complete control over which of a well-defined set of “dangerous” methods are 
allowed to be called by any given class. It takestherealmsfrom thelast section into account, the 
source (origin) of the class, and the type of the class (stand-alone, or loaded by an applet). Each 
of these can be separately configured to have the effect you (the programmer) likeon your J ava 
system. F or nonprogrammers, thesysten providesseveral levels of default security policiesfrom 
which you can choose. 


W hat is this “well-defined set” of methods that are protected? 


Filel/O isapart of the set, for obviousreasons. Applets, by default, can open, read, or writefiles 
only with the express permission of the user— and even then, only in certain restricted 
directories. (O f course, users can always be stupid about this, but that’s what system adminis- 
trators are for!) 


Also in this protected set are the methods that create and use network connections, both 
incoming and outgoing. 


The final members of the set are those methods that allow one thread to access, control, and 
manipulate other threads. (O f course, additional methods can be protected as well, by creating 
anew subclass of securitymanager that handles them.) 


For both file and network access, the user of a J ava-aware browser can choose between three 
realms (and one subrealm) of protection: 

“J unrestricted (allows applets to do anything) 
firewall (allows applets within the firewall to do anything) 


source (allows applets to do things only with their origin {Internet} host, or with other 
applets from there) 


[| local (disallows all file and network access) 


For file access, the source subrealm is not meaningful, so it really has only three realms of 
protection. (Asa programmer, of course, you have full access to the security manager and can 
set up your own peculiar criteria for granting and revoking privileges to your heart’s content.) 


For network access, you can imagine wanting many more realms. For example, you might 
specify different groups of trusted domains (companies), each of which is allowed added 
privileges when applets from that group are loaded. Some groups can be more trusted than 
others, and you might even allow groups to grow automatically by allowing existing menbers 
to recommend new members for admission. (T he Java seal of approval?) 


In any case, thepossibilitiesareendless, aslong asthereisasecureway of recognizingtheoriginal 
creator of an applet. 


You might think this problem has already been solved, because classes are tagged with their 
origin. In fact, the] ava run-time goes far out of its way to be sure that that origin information 
isnever lost— any executing method can bedynamically restricted by thisinformation anywhere 
in the call chain. So why isn’t this enough? 


Because what you'd really like to be ableto do is permanently “tag” an applet with its original 
creator (itstrue origin), and no matter whereit has traveled, a browser could verify the integrity 
and authenticate the creator of that applet. Just because you don’t know the company or 
individual that operatesaparticular server machinedoesn’t mean that you want to mistrust every 
applet stored on that machine. It’sjust that, currently, to bereally safe, you should mistrust those 
applets, however. 


If somehow those applets were irrevocably tagged with a digital signature by their creator, and 
that signature could also guaranteethat the applet had not been tampered with, you’d begolden. 


Note: Luckily, Sun is planning to do exactly that for Java, as soon as export 
restrictions can be resolved. 


H ere’s ahelpful hint of where the team would like to go, from the security docu- 
mentation: “...a mechanism exists whereby public keys and cryptographic message 
digests can be securely attached to code fragments that not only identify who 
originated the code, but guarantee its integrity as well. T his latter mechanism will 
be implemented in future releases.” 


Look for these sorts of features in every release of | ava; they will be a key part of the 
future of the Internet! 


Onefinal note about security. D espite the best efforts of the] ava team, there is always a trade 
off between useful functionality and absolute security. For example, Java applets can create 
windows, an extremely useful capability, but a “nasty” applet could usethisto spoof theuser into 
typing private password information, by showing a familiar program (or operating system) 
window and then asking an expected, legitimate looking question in it. (T he beta release adds 
a special banner to applet-created windows to solve this problem.) 


Flexibility and security can’t both be maximized. Thus far on the N et, people have chosen 
maximum flexibility, and havelived with theminimal security theN et now provides. Let’shope 
that Java can help tip the scales a bit, enabling much better security, while sacrificing only a 
minimal amount of the flexibility that has drawn so many to the N et. 
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Summary 


T oday, you learned about the grand vision that someof us have for J ava, and about the exciting 
future it promises. 
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Under the hood, theinner workings of the virtual machine, the bytecodeinterpreter (and all its 
bytecodes), the garbage collector, the class loader, the verifier, the security manager, and the 
powerful security features of J ava were all revealed. 


You now Know almost enough to writeaJ avarun-time environment of your own— but luckily, 
you don’t have to. You can simply download the latest release of J ava— or use a J ava-aware 
browser to enjoy most of the benefits of J ava right away. 


| hope that J ava ends up opening new roadsin your mind, asit hasin mine. 


Q&A 


Q 


A 


co) 


I’m still a little unclear about why the J ava language and compiler make the N et 
safer. C an’t they just be “side-stepped” by nasty bytecodes? 

Yes, they can— but don’t forget that the whole point of using a safe language and 
compiler was to make the N et asa whole safer as more] ava code is written. An 
overwhelming majority of this J ava code will be written by “honest” Java program- 
mers, who will produce safe bytecodes. T his makes the N et more predictable over 
time, and thus more secure. 


| know you said that garbage collection is something | don’t have to worry 
about, but what if | want (or need) to? 


So, you are planning to fly a plane with J ava. Cool! For just such cases, there is a way 
to ask the J ava run-time, during startup (java -noasyncgc), not to run garbage 
collection unless forced to, either by an explicit call (system. gce()) or by running out 
of memory. (T his can be quite useful if you have multiple threads that are messing 
each other up and want to “get the gc thread out of the way” while testing them.) 

D on’t forget that turning garbage collection off means that any object you create will 
live along, long time. If you're real-time, you never want to “step back” for a full ge— 
so be sure to reuse objects often, and don’t create too many of them! 


| like the control above; is there anything else! can do to the garbage collector? 


You can also force the finalize() methods of any recently freed objects to be called 
immediately via system. runFinalization(). You might want to do thisif you’re about 
to ask for some resources that you suspect might still be tied up by objects that are 
“gone but not forgotten” (waiting for tinalize()). Thisis even rarer than starting age 
by hand, but it’s mentioned here for completeness. 


Q What's the last word on J ava? 


A _Javaadds much more than it can ever take away. It has always done so for me, and 
now, | hope it will for you, as well. 
The future of the N et is filled with as-yet-undreamt horizons, and the road is long and 
hard, but J ava is a great traveling companion. 
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A y Language Summary 


T his appendix contains a summary or quick reference for the] avalanguage, as described in this 
book. 


Technical N ote: T his is not a grammar overview, nor is it a technical overview of 
the language itself. It’s a quick reference to be used after you already know the 
basics of how the language works. If you need atechnical description of the 
language, your best bet is to visit the] ava W eb Site (http: //java.sun.com) and 
download the actual specification, which includes a full BN F grammar. 


Language keywords and symbols are shown in amonospace font. Arguments and other parts to 
be substituted are in italic monospace. 


O ptional parts are indicated by brackets (except in the array syntax section). If there are several 
options that are mutually exclusive, they are shown separated by pipes ({! 1) like this: 


[ public | private | protected ] type varname 


Reserved Words 


T he following words are reserved for use by the] ava language itself (some of them are reserved 
but not currently used). You cannot use these words to refer to classes, methods, or variable 


names: 
abstract do implements package throw 
boolean double import private throws 
break else inner protected transient 
byte extends instanceof public try 
case final int rest var 
cast finally interface return void 
catch float long short volatile 
char for native static while 
class future new sure 
const generic null switch 
continue goto operator synchronized 
default if outer this 


474 


Comments 


/* this is a multiline comment */ 


// this is a single-line comment 


/** Javadoc comment */ 


Literals 


number 

number[1 [;] L] 
Oxhex 

@Xhex 

Goctal 

[ number ].number 
number[ f [{] f] 
number[ d [;] D] 
[ + [|] - ] number 
numberenumber 
numberEnumber 
‘character' 
"characters" 

\b 

\t 

\n 


\\ 
\UNNNN 
true 


false 


T ype int 

T ype long 

H ex integer 

H ex integer 

O ctal integer 

T ype double 

T ype float 

T ype double 
Signed 
Exponent 
Exponent 
Single character 
String 

Empty string 
Backspace 

Tab 

Line feed 

Form feed 
Carriage return 
D ouble quote 
Single quote 
Backslash 

U nicode escape (NNNN is hex) 
Boolean 
Boolean 
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Variable Declaration 


[ byte | short | int ! long ] varname Integers (pick one type) 
[ float | double ] varname Floats (pick one type) 
char varname; Characters 

boolean varname Boolean 

classname varname; Class types 
interfacename varname Interface types 

type varname, varname, varname; M ultiple variables 


T he following options are available only for class and instance variables. Any of these options 
can be used with a variable declaration 


[ static ] variableDeclaration Class variable 

[ final ] variableDeclaration Constants 

[ public | private | protected ] variableDeclaration Access control 

[volatile] varname M odified asynchro- 
nously 

[transient] varname Not persistent 


(not yet implemented) 


Variable Assignment 


variable = value Assignment 
variablet++ postfix Increment 
++variable Prefix Increment 
variable-- Postfix D ecrement 
--variable Prefix D ecrement 
variable += value Add and assign 
variable -= value Subtract and assign 
variable *= value M ultiply and assign 
variable += value Divide and assign 
variable %= value M odulus and assign 
variable & value AND and assign 
variable |= value or and assign 
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variable “= value 
variable <<= value 
variable >>= value 


variable >>>= value 


Operators 


arg + arg 
arg - arg 
arg * arg 
arg + arg 
arg % arg 
arg < arg 
arg > arg 
arg < arg 
arg > arg 
arg == arg 
arg #arg 
arg && arg 
arg \; arg 
! arg 

arg & arg 
arg ; arg 
arg * arg 
arg << arg 
arg >> arg 
arg >>> arg 
~ arg 
(type) thing 
arg instanceof class 


test ? trueOp : falseOp 


xor and assign 

Left-shift and assign 
Right-shift and assign 
Zero-fill right-shift and assign 


Addition 
Subtraction 

M ultiplication 
Division 

M odulus 

Less than 

Greater than 

Less than or equal to 
Greater than or equal to 
Equal 

N ot equal 

Logical anp 

Logical or 

Logical not 

AND 

OR 

XOR 

Left-shift 
Right-shift 

Zero-fill right-shift 
Complement 
Casting 

Instance of 

T enary (it) operator 
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Objects 


new class () 

new class(arg,arg,arg...) 
object.variable 
object.classvar 


Class.classvar 


object.method() 
object.method(arg,arg,arg...) 
object.classmethod() 
object.classmethod(arg,arg,arg...) 
Class.classmethod() 


Class.classmethod(arg,arg,arg...) 


Arrays 


Note: T he brackets in this section 


Create new instance 

N ew instance with parameters 
Instance variable 

Class variable 

Class variable 


Instance method (no args) 
Instance method 

Class method (no args) 
Class method 

Class method (no args) 
Class method 


are parts of the array creation or access 


statements. T hey do not denote optional parts as they do in other parts of this 


appendix. 


type varname[] 

type[] varname 

new type[numElements ] 
array[index] 


array.length 


Array variable 
Array variable 

N ew array object 
Element access 
Length of array 


Loops and Conditionals 


if ( test) block 
if ( test ) block 


Conditional 
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else block Conditional with ese 


switch (test) { switch (only with integer or char types) 


case value : statement 


case value : statement 


default : statement 


} 


for (initializer, test, change ) block for loop 


while ( test ) block while loop 

do block do loop 

while (test) 

break [ label ] break from loop Or switch 
continue [ label ] continue loops 

label: Labeled loops 


Class D efinitions 


class classname block Simple Class definition 


Any of the following optional modifiers can be added to the class definition: 


[ final ] class classname block Cannot be subclassed 

[ abstract ] class classname block Cannot be instantiated 

[ public ] class classname block Accessible outside 
package 

class classname [ extends Superclass ] block D efine superclass 

class classname [| implements interfaces ] block Implement oneor more 
interfaces 


Method and Constructor Definitions 


T he basic method looks like this, where returnType is atype name, a class name, or void. 


returnType methodName() block Basic method 
returnType methodName(parameter, parameter, ...) block Method with parameters 479 
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M ethod parameters look like this: 


type parameterName 


M ethod variations can include any of the following optional keywords: 


[ abstract ] returnType methodName() block Abstract method 

[ static ] returnType methodName() block Class method 

[ native ] returnType methodName() block N ative method 

[ final ] returnType methodName() block final method 

[ synchronized ] returnType methodName() block Thread lock before 
executing 

[ public | private | protected ] returnType methodName () Block access control 


Constructors look like this: 


classname() block basic constructor 

classname(parameter, parameter, parameter...) block constructor with 
parameters 

[ public | private | protected] classname ()block Access control 


In the method/constructor body you can use these references and methods: 


this Refers to current object 
super Refers to superclass 

super .methodName () Call a superclass’s method 
this(...) Calls class's constructor 
super(...) Calls superclass’s constructor 
return [ value ] Returns a value 


Packages, Interfaces, and Importing 


import package .className Imports specific class name 

import package .* Imports all public classes in 
package 

package packagename Classes in this file belong 
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interface interfaceName [ extends anotherInterface ] block 


[ public ] interface interfaceName block 


[ abstract ] interface interfaceName block 


Exceptions and Guarding 


synchronized ( object ) block W aits for lock on object 

try block Guarded statenents 

catch ( exception ) block Executed if exceotion is thrown 
[ finally block ] Cleanup code 

try block Same as previous example (can 
[ catch ( exception ) block ] use optional catch or finally, 
finally block but not both) 
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Class Hierarchy 
Diagrams 


by Charles L. Perkins 
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“8. Class Hierarchy Diagrams 


java.applet 
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Class Hierarchy Diagrams 


| Unarownirar j java lang-errors 
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ava.lang-exceptions 
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CasssNctf ound arepoon 
InetariationException 
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ArrayindexQurOBeurdsEecaption 


Runtrmet ception 
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jeve.lo 
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Class Hierarchy Diagrams 
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java.awt-components 


si we 
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Class Hierarchy Diagrams 
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java.awt.peer 
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Class Hierarchy Diagrams 
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java.util 
Hash Table Propertes 
Hash TableErtry 
= ca I> package 
“s | Haan TabieEnunerator 
3a oom t> package 
ies ~ 
VectorEnumerstor 
ooar 1 package 
ObserverLet 
 vecter| — 
Thrcecatiie (Stack | 
es] 
Exception 
pave aNQeuceptors . ree 
RurtimeE sceagtion 
pave Angeaceptorw NoSuch€ emertE ecapiicn 


About T hese Diagrams 


Thediagramsin this appendix are class hierarchy diagrams for the package java and for all the 
subpackages recursively below it in the J ava beta binary release. 


Each page contains the class hierarchy for one package (or a subtree of a particularly large 
package) with all its interfaces included, and each class in this tree is shown attached to its 
superclasses, even if they are on another page. A detailed key is located on the first page of this 
appendix. 


Note: win32Process and UNIXProcess appear in their respective distributions of 
Java, but both implement (essentially) the same protocol as their common abstract 
superclass— Process— SO only it was included. T his means that are no platform- 
dependent classes in the diagrams. (Of course, each release actually has some such 
Classes in its .class directories.) Several abstract Classes have no subclasses in the 
documented library, but any concrete implementation of J ava would define 
subclasses of then. 


| supplemented the (incomplete) API documentation by looking through all the source files 
(below src/java) to find all the (missing) package classes and their relationships. 


|’veheard therearevariousprogramsthat auto-layout hierarchiesfor you, but! did thesetheold- 
fashioned way (in other words, | earned it, as] .H . used to say). O nenice side effect isthat these 
diagramsshould bemorereadablethan acomputer would produce, though you will haveto live 
with my aesthetic choices (sorry). | chose, for example, to attach linesthrough thecenter of each 
class node, something which | think looksand feels better overall (to me) but which on occasion 
can be alittle confusing. Follow lines through the center of the classes (not at the corners, nor 
along any line not passing through the center) to connect the dots mentally. 
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The J) ava Class 
Library 


by Laura Lemay 


C y The J ava Class Library 


T his appendix provides a general overview of the classes availablein the standard J ava packages 
(that is, the classes that are guaranteed to be available in any Java implementation). This 
appendix isintended for general reference; for moreinformation about classinheritanceand the 
exceptions defined for each package, seeA ppendix B. For morespecific information about each 
variable and the methods within each class, see the API documentation from Sun at http: // 
java.sun.com. 
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java.lang 
The java. 1ang package contains the classes and interfaces that makeup the core] ava language. 
Interfaces 
Runnable M ethods for classes that want to run as threads 
Classes 
Boolean O bject wrapper for boolean values 
Character O bject wrapper for char values 
Class Run-time representations of classes 
ClassLoader Abstract behavior for handling loading of classes 
Double O bject wrapper for double values 
Float O bject wrapper for float values 
Integer O bject wrapper for int values 
Long O bject wrapper for 10ng values 
Math Utility class for math operations 
Number Abstract superclass of all number classes (Integer, 
Float, and so on) 
Object Generic object Class, at top of inheritance hierarchy 
Process Abstract behavior for processes such as those spawned 
using methods in the system class 
Runtime Access to the] ava run-time 
SecurityManager Abstract behavior for implementing security policies 
String Character strings 
StringBuffer M utable strings 
System Access to J ava’s system-level behavior, provided in a 


platform-independent way 


Thread 


ThreadGroup 
Throwable 


java.util 


M ethods for managing threads and classes that run in 
threads 


A group of threads 


Generic Exception class; all objects thrown must bea 
Throwable 


The java.util package contains various utility classes and interfaces, including random 
numbers, system properties, and other useful classes. 


Interfaces 


Enumeration 
O bserver 


Classes 


BitSet 
Date 


Dictionary 


Hashtable 
Observable 


Properties 


Random 
Stack 


StringTokenizer 


Vector 


M ethods for enumerating sets of values 


M ethods for allowing classes to observe observable 
objects 


A set of bits 

The current system date, as well as methods for 
generating and parsing dates 

An abstract class that maps between keys and values 
(superclass of HashTable) 


A hash table 
An abstract class for observable objects 


A hashtable that contains behavior for setting and 
retrieving persistent properties of the system or of a 
Class 


U tilities for generating random numbers 

A stack (a last-in-first-out queue) 

Utilities for splitting strings into a sequence of 
individual “tokens” 

A growable array of objects 
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java.io 
The java.io package provides input and output classes and interfaces for streams and files. 
Interfaces 
D atalnput M ethods for reading machine-independent typed 
input streams 
D ataO utput M ethods for writing machine-independent typed 
output streams 
Filename ilter M ethods for filtering file names 
Classes 
BufferedInputStream A buffered input stream 
BufferedOutputStream A buffered output stream 
ByteArrayInputStream An input stream from a byte array 
ByteArrayOutputStream An output stream to a byte array 
DataInputStream Enables you to read primitive J ava types 


(intS, chars, booleans, and so on) from a 
stream in a machine-independent way 
DataOutputStream Enables you to write primitive J ava data 
types (intS, chars, booleans, and so on) toa 
stream in a machine-independent way 


File Represents a file on the host’s file system 

FileInputStream An input stream from a file, constructed 
using a filename or descriptor 

FileOutputStream An output stream to a file, constructed using 
a filename or descriptor 

FilterInputStream Abstract class which provides a filter for 


input streams (and for adding stream 
functionality such as buffering) 


FilterOutputStream Abstract class which provides a filter for 
output streams (and for adding stream 
functionality such as buffering) 

InputStream An abstract class representing an input 
stream of bytes; the parent of all input 
streams in this package 
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LineNumberInputStream An input stream that keeps track of line 
numbers 
OutputStream An abstract class representing an output 


stream of bytes; the parent of all output 
streams in this package 


PipedInputStream A piped input stream, which should be 
connected to a PipedoutputStream to be 
useful 

PipedOutputStream A piped output stream, which should be 


connected to a PipedInputStream to be 
useful (together they provide safe communi- 
cation between threads) 


PrintStream An output stream for printing (used by 
System.out.printIn(... )) 

PushbackInputStream An input stream with a 1-byte push back 
buffer 

RandomAccessFile Provides random-access to a file, constructed 
from filenames, descriptors, or objects 

SequenceInputStream Converts a sequence of input streams into a 
single input steam 

StreamTokenizer Converts an input stream into a sequence of 
individual tokens 

StringBufferInputStream An input stream from a stringBufter object 

java.net 


The java.net package contains classes and interfaces for performing network operations, such 
as sockets and URLs. 


Interfaces 
ContentH andlerF actory M ethods for creating contentHandler objects 
Socket! mplF actory M ethods for creating socket implementa- 
tions (instance of the socket Imp1 Class) 
U RLStreamH andlerF actory M ethods for creating uRLStreamHandler 
objects 
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Classes 


ContentHandler 


InetAddress 


ServerSocket 
Socket 
SocketImpl 
URL 


URLConnection 


URLStreamHandler 


java.awt 


Abstract behavior for reading data from aU RL 
connection and constructing the appropriate local 
object, based on MIME types 


An object representation of an Internet host (host 
name, IP address) 


A server-side socket 

A socket 

An abstract class for specific socket implenentations 
An object representation of aU RL 

Abstract behavior for a socket that can handle various 
W eb-based protocols (http, #tp, and so on) 

Abstract class for managing streams to object refer- 
enced by URLs 


T he java.awt package containsthe classes and interfacesthat makeup theAbstract W indowing 


Toolkit. 


Interfaces 


LayoutManager 


MenuContainer 


Classes 


BorderLayout 


Button 


Canvas 


CardLayout 
Checkbox 
CheckboxGroup 


CheckboxMenuItem 


M ethods for laying out containers 
M ethods for menu-related containers 


A layout manager for arranging items in border 
formation 


A UI pushbutton 


A canvas for drawing and performing other graphics 
operations 


A layout manager for H yperC ard-like metaphors 
A checkbox 

A group of exclusive checkboxes (radio buttons) 
A toggle menu item 


Choice A popup menu of choices 

Color An abstract representation of a color 

Component T he abstract generic class for all Ul components 

Container Abstract behavior for a component that can hold 
other components or containers 

Dialog A window for brief interactions with users 

Dimension Width and height 

Event An object representing events caused by the system or 
based on user input 

FileDialog A dialog for getting file names from the local file 
system 

FlowLayout A layout manager that lays out objects from left to 
right in rows 

Font An abstract representation of a font 

FontMetrics Abstract class for holding information about a specific 
font’s character shapes and height and width infor- 
mation 

Frame A top-level window with atitle 

Graphics Abstract behavior for representing a graphics context, 
and for drawing and painting shapes and objects 

GridBagConstraints Constraints for components laid out using 
GridBagLayout 

GridBagLayout A layout manager that aligns components horizon- 
tally and vertically based on their values from 
GridBagConstraints 

GridLayout A layout manager with rows and columns; ements 
are added to each cell in the grid 

Image An abstract representation of a bitmap image 

Insets Distances from the outer border of the window; used 
to lay out components 

Label A text label for UI components 

List A scrolling list 

MediaTracker A way to keep track of the status of media objects 
being loaded over the net 

Menu A menu, which can contain menu items and isa 


container on a menubar 
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MenuBar 
MenuComponent 
MenuItem 
Panel 

Point 

Polygon 
Rectangle 


Scrollbar 
TextArea 
TextComponent 
TextField 
Toolkit 


Window 


java.awt.image 


A menubar (container for menus) 

T he abstract superclass of all menu elements 
An individual menu iten 

A container that is displayed 

x and y coordinates 

A set of points 


x and y coordinates for the top corner, plus width and 
height 


A UI scrollbar object 

A multiline, scrollable, editable text fidd 

T he superclass of all editable text components 
A fixed-size editable text field 


Abstract behavior for binding the abstract AW T 
classes to a platform-specific toolkit implementation 


A top-level window, and the superclass of the Frame 
and Dialog classes 


The java.awt. image package is a subpackage of the AWT that provides classes for managing 


bitmap images. 


Interfaces 


ImageConsumer 
ImageObserver 


ImageProducer 


Classes 


ColorModel 


CropImageFilter 
DirectColorModel 


M ethods for receiving image data created by an 
ImageProducer 

M ethods to track the loading and construction of an 
image 

M ethods to construct or filter image data 


An abstract class for managing color information for 
images 
A filter for cropping images to a particular size 


A specific color model for managing and translating 
pixel color values 


FilteredImageSource An ImageProducer that takes an image and an 
ImageFilter Object and produces an image for an 
ImageConsumer 

ImageFilter A filter that takes image data from an ImageProducer, 
modifies it in some way, and hands it off to a 
ImageConsumer 

IndexColorModel A specific color model for managing and translating 
color values in a fixed-color map 

MemoryImageSource An image producer that gets its image from memory; 
used to construct an image by hand 

RGBImageFilter Abstract behavior for a filter that modifies the RGB 


values of pixelsin RGB images 


java.awt. peer 


The java.awt.peer package is a subpackage of AWT that provides the (hidden) platform- 
specific AWT classes (for example, for M otif, Macintosh, or Windows 95) with platform- 
independent interfaces to implement. T hus, callers using theseinterfaces need not know which 
platform’s window system these hidden AWT classes are currently implementing. 


Each classin theAWT thatinheritsfrom either component Or MenuComponent haSacorresponding 
peer class. Each of those classes is the name of the component with -peer added (for example, 
ButtonPeer, DialogPeer, and windowPeer). Becauseeach one provides similar behavior, they are 
not enumerated here 


java.applet 
The java. applet package provides applet-specific behavior. 

Interfaces 
AppletContext M ethods to refer to the applet’s context 
AppletStub M ethods for nonbrowser applet viewers 
AudioClip M ethods for playing audio files 

Classes 
Applet T he base applet class 
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How J ava Differs 
from C and C++ 


by Laura Lemay 


DY How J ava Differs from C and C++ 


T hisappendix contains adescription of most of themajor differencesbetween C, C++, and the 
Java language. If you area programmer familiar with eather C or C-H, you may want to review 
thisappendixto catch someof thecommon mistakesand assumptionsprogrammersmakewhen 
using J ava. 


P ointers 


Java does not have an explicit pointer type. Instead of pointers, all references to objects— 
including variable assignments, arguments passed into methods, and array eenents— are 
accomplished by usingimplicit references. R eferencesand pointersareessentially thesamething 
except that you can’t do pointer arithmetic on references (nor do you need to). 


Referencesemanticsalso enablestructures such aslinked liststo becreated easily in J ava without 
explicit pointers; merely create a linked list node with variables that point to the next and the 
previous node Then, to insert itemsin the list, assign those variables to other node objects. 


Arrays 


Arraysin J avaarefirst class objects, and referencesto arrays and their contents are accomplished 
through explicit references rather than via point arithmetic. Array boundaries are strictly 
enforced; attempting to read past the ends of an array isa compile or run-time error. As with 
other objects, passing an array to amethod passes a reference to the original array, so changing 
the contents of that array reference changes the original array object. 


Arrays of objects are arrays of references that are not automatically initialized to contain actual 
objects. U sing thefollowing] avacodeproducesan array of typemyobj ect with ten dements, but 
that array initially contains only nulls: 


MyObject arrayofobjs[] = new MyObject[10]; 
You must now add actual myobject objects to that array: 
for (int i; i< arrayofobjs.length. i++) { 
arrayofobjs[i] = new MyObject(); 
J ava doesnot support multidimensional arraysasin C and C-H. In] ava, you must create arrays 
that contain other arrays. 


Strings 
Stringsin C and C ++ are arrays of characters, terminated by a null character (\o). To operate 
on and manage strings, you treat them as you would any other array, with all the inherent 


difficulties of keeping track of pointer arithmetic and being careful not to stray off the end of 
the array. 
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Strings in Java are objects, and all methods that operate on strings can treat the string as a 
complete entity. Strings are not terminated by anull, nor can you accidentally overstep the end 
of a string (like arrays, string boundaries are strictly enforced). 


Memory Management 


All memory management in Java is automatic; memory is allocated automatically when an 
object iscreated, and arun-timegarbagecollector (the“GC ”) freesthat memory when theobject 
isno longer in use. C’S malloc and free functions do not exist in Java. 


To “force” an object to be freed, remove all references to that object (assign variables holding 
it to null, remove it from arrays, and so on). The next time the Java GC runs, that object is 
reclaimed. 


D ata Types 


Asmentioned in the early part of this book, all J ava primitive data types (char, int, long, and 
so on) have consistent sizes and behavior across platforms and operating systems. T hereareno 
unsigned data types asin C and C ++ (except for char, which isa 16-bit unsigned integer). 


T heboolean primitive data type can have two values: true Or false. Boolean isnot an integer, 
nor can it betreated as one, although you cannot cast o or 1 (integers) to boolean typesin Java. 


Composite data types are accomplished in J ava exclusively through the use of class definitions. 
The struct, union, and typedef keywords have all been removed in favor of classes. 


Casting between datatypesismuch morecontrolled in J ava; automatic casting occursonly when 
there will be no loss of information. All other casts must be explicit. T he primitive data types 
(int, float, long, char, boolean, and So on) cannot be cast to objects or vice versa; there are 
methods and special “wrapper” classes to convert values between objects and primitive types. 


Operators 


O perator precedence and association behaves as it does in C. Note, however, that the new 
keyword (for creating a new object) binds tighter than dot notation (.), which is different 
behavior from C +. In particular, note the following expression: 


new foo().bar; 
T his expression operates as if it were written like this: 
(new foo()).bar; 


O perator overloading, asin C +4, cannot beaccomplished in Java. The, operator of C hasbeen 
deleted. 
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T he>>> operator producesan unsigned logical right shift (remember, thereareno unsigned data 
types). 
The + operator can be used to concatenate strings. 


Control Flow 


Although the if, while, for, and do statements in J ava are syntactically the same as they arein 
C andC H, thereisonesignificant difference. T hetest expression for each control flow construct 
must return an actual boolean value (true or false). In C and CH, the expression can return 
an integer. 


Arguments 


Java does not support mechanisms for optional arguments or for variable-length argument lists 
to functionsasin C and C H. All method definitions must haveaspecific number of arguments. 


Command-lineargumentsin J avabehavedifferently from thosein C andC H.T hefirst dement 
in the argument vector (argv[@}) inC and C ++isthename of the program itself; in J ava, that 
first argument isthefirst of the additional arguments. In other words, in] ava, argv[0] iSargv[1] 
in C and C+ thereis no way to get hold of the actual name of the] ava program. 


Other Differences 


The following other minor differences from C and C ++ exist in J ava: 


“| Java does not havea preprocessor, and as such, does not have #defineS or macros. 
Constants can be created by using the final modifier when declaring class and instance 
variables. 

Java does not have template classes as in C -H. 


Java does not include C's const keyword or the ability to pass by const reference 

explicitly. 

(| Java classes are singly inherited, with some multiple inheritance features provided 
through interfaces. 

"| All functions are implemented as methods. T here are no functions that are not tied to 
Classes. 

_ The goto keyword does not exist in J ava (it’s a reserved word, but currently 

unimplemented). You can, however, use labeled breaks and continues to break out of 

and continue executing complex switch or loop constructs. 


